10 added, 0 removed. Audit A to A.
# codemem
- Public repo: never add secrets, internal hostnames, private identifiers, or local artifact paths. Keep `.tmp/`, `.venv/`, `*.sqlite`, `packages/*/dist/`, `packages/viewer-server/static/`, and `.opencode/package-lock.json` out of git.
- Default to the TypeScript toolchain: this repo is a pnpm workspace on Node 24; use the pnpm version pinned by the root `packageManager` field.
## What runs where
- CLI entrypoint: `packages/cli/src/index.ts` (`pnpm run codemem ...`).
- Shared store/search/sync logic and exported version: `packages/core/src/index.ts`.
- Viewer HTTP API + SPA host: `packages/viewer-server/src/index.ts`.
- Viewer UI source: `packages/ui/src/`.
- OpenCode plugin source of truth: `packages/opencode-plugin/.opencode/plugins/codemem.js`.
- `packages/cli/.opencode/plugins/codemem.js` and repo-root `.opencode/plugins/codemem.js` are wrappers/re-exports, not the main implementation.
- `packages/cloudflare-coordinator-worker/` is its own worker package with separate tests.
## Commands worth using
- Install: `pnpm install`
- Full local gate / CI order: `pnpm run tsc && pnpm run lint && pnpm run test` (`pnpm run check`)
- Build everything: `pnpm run build`
- Run CLI from source: `pnpm run codemem --help`
- Run one vitest file: `pnpm exec vitest run packages/cli/src/commands/serve.test.ts`
- Run one package script: `pnpm --filter codemem test`, `pnpm --filter @codemem/ui build`, `pnpm --filter @codemem/cloudflare-coordinator-worker test:worker`
- E2E smoke: `CODEMEM_E2E_BUILD=1 CODEMEM_E2E_JSON=1 pnpm run e2e:smoke -- --json` (artifacts land in `.tmp/e2e-artifacts`)
## Gotchas agents usually miss
- `pnpm run lint` only checks files included by `biome.json` (mostly `packages/**` TS/TSX/JS/JSON and root TS config). Docs like `AGENTS.md` are outside Biome.
- `pnpm run test` is workspace vitest; root `vitest.config.ts` points at `packages/*/vite.config.ts`.
- The viewer server throws if `packages/viewer-server/static/index.html` is missing. If you change UI or viewer assets, run `pnpm build` or at least `pnpm --filter @codemem/ui build`.
- `packages/viewer-server/static/` is generated and ignored. Do not hand-edit it. UI build stages `packages/ui/static/` there alongside the built `app.js` bundle.
- Plugin smoke tests rely on nested `.opencode` runtime deps. CI installs `@opencode-ai/plugin` inside `packages/cli/.opencode` and `packages/opencode-plugin/.opencode` before running smoke tests.
- CLI work should follow `docs/cli-design-conventions.md`: max 2 nesting levels, noun-based groups, shared `--db-path` / `--config` / `--json` helpers, and no uncaught throws from command handlers.
- The repo is TS-first; trust `package.json`, package scripts, and CI over older migration-era docs/checklists.
- `.github/PULL_REQUEST_TEMPLATE.md` is TS-first now; use `pnpm run tsc`, `pnpm run lint`, and `pnpm run test` for normal changes.
## Workflow rules specific to this repo
- Use `bd` for issue tracking, not markdown TODOs: `bd ready --json`, `bd create ... --json`, `bd close ... --json`.
- If you change plugin behavior, update `README.md` and any affected docs under `docs/`.
- If you change memory kinds or their presentation, update all three surfaces together: `packages/core/src/store.ts`, `packages/mcp-server/src/index.ts`, and `packages/ui/src/tabs/feed.ts`.
+ ## Code shape
+
+ - Replace nested ternaries with branches or a lookup.
+ - Use guard clauses instead of nesting preconditions.
+ - Pass named options instead of opaque boolean literals; predicate return values are fine.
+ - Extract named stages when a function needs comments to label its sections.
+ - Use JSX ternaries only for single-expression leaves; move branching outside nested markup.
+ - Treat `[lint-feedback]` new or worsened diagnostics returned after an edit as blocking for that edit and fix them locally. Legacy warnings outside the edit should not trigger broad cleanup.
+ - Use `packages/viewer-server/src/request-rate-limit.ts`, `packages/cli/src/shared-options.ts`, and `packages/cli/src/help-style.ts` as reference exemplars only.
+
## Release traps
- Release tags trigger publishing. Tag only the merged `main` commit, not a `release/*` branch tip.
- Version alignment is scripted in `scripts/release-version.mjs`; tag safety is enforced by `pnpm run release:preflight-tag` / `scripts/release-tag-preflight.sh`.
- Releases publish to the public npm registry; keep `.opencode/.npmrc` pointed at `https://registry.npmjs.org/`.