Skip to content

Docs: packages/core/README.md and CONTRIBUTING.md carry false claims and broken URLs #306

Description

@Deodat-Lawson

Found while correcting the root README.md in #301. The root README and REPOSITORY.md are fixed; these three files were left alone and still carry the same errors. The root README currently links to packages/core/README.md as the API reference while flagging it inline as out of date — that workaround should go away once this is fixed.

1. packages/core/package.json — wrong repo in published metadata

Highest priority, because this ships. The package is publish-ready (publishConfig redirects main, types and exports to ./dist/*), so whenever release plumbing is fixed, npm would show links to a repository that does not exist.

Field Current Should be
homepage https://github.com/launchstack/launchstack https://github.com/Deodat-Lawson/LaunchStack
repository.url https://github.com/launchstack/launchstack.git https://github.com/Deodat-Lawson/LaunchStack.git

2. packages/core/README.md — four false claims

Line Claim Reality
5 "Core reads zero environment variables at runtime" Six files under packages/core/src read process.env: crypto/secret-box.ts, embeddings/company-config.ts, providers/ner/llm.ts, providers/ner/sidecar.ts, providers/reranking/jina.ts, providers/reranking/sidecar.ts. The two sidecar.ts files read SIDECAR_URL at module load with a hardcoded http://localhost:8000 default that cannot be set through CoreConfig at all.
10, 12 pnpm add @launchstack/core … The registry returns 404 — never published. Blocked by a missing .changeset/ and by release.yml:20 being gated on github.repository == 'launchstack/launchstack', so the release job is skipped on every push.
29 embeddings: { indexName: "openai-3-small" } Not a registered index. resolveEmbeddingIndex() throws. The static index is legacy-openai-1536 (embeddings/index-registry.ts:55), which is what .env.example:39 sets. The same bogus value also appears in the CoreConfig doc comment at config/types.ts:89.
39 await engine.rag?.port.search({ query }) Engine exposes only config, db, dbHandle, storage, neo4j, close (src/index.ts:29-47). There is no rag field, and RagPort's only method is companyEnsembleSearch (rag/types.ts:19). Doubly wrong — the sample cannot run.

3. CONTRIBUTING.md — broken URLs and an overstated lint claim

Five links point at github.com/launchstack/launchstack, including the git clone command, which 404s for anyone following the guide:

  • :8 — existing issues + discussions
  • :37git clone
  • :103 — discussions
  • :104 — new issue

Separately, :24 says "Violations fail lint." They do not: the CI lint step is continue-on-error: true under the heading "Lint (legacy baseline, non-blocking)" (CI.yml:69), and six core files violate the no-process.env rule today. The root README now words this as "ESLint declares these boundaries, but the lint step is non-blocking in CI and there is an existing violation baseline."

Acceptance criteria

  • packages/core/package.json homepage and repository.url point at the real remote
  • packages/core/README.md has no claim contradicted by the code; its code sample compiles against the real Engine and CoreConfig
  • config/types.ts:89 doc comment no longer references openai-3-small
  • All launchstack/launchstack URLs across the repo resolve — grep -rn "launchstack/launchstack" --exclude-dir=node_modules . returns only the intentional release.yml gate, or that gate is fixed too
  • CONTRIBUTING.md:24 describes lint enforcement accurately
  • The "out of date" warning in the root README pointing at packages/core/README.md is removed

Note

release.yml:20's repo-slug gate is the reason no release has ever run. Fixing it is out of scope here but worth tracking — it is recorded in REPOSITORY.md.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions