docs: consolidate knowledge system and deploy guardrails - #19
Conversation
Build a maintainable, local-first repository knowledge system. Markdown
under docs/ is the source of truth; Blume (blume.config.ts) is only the
presentation + search layer.
Created:
- docs/index.md (navigation hub), docs/product/{overview,surfaces}.md
- docs/architecture/{overview,data-model}.md + 5 ADRs + ADR template
- docs/development/{workflow,docs}.md
- docs/operations/{ci,deploy,release-verify}.md, jobs/{company-watchlist-sync,weekly-digest}.md, runbooks/{apply-agent-cli,landing-astro}.md
- docs/knowledge/{failed-approaches,security-audit}.md, learnings/new-things.md
- STATUS.md (short view), blume.config.ts, scripts/check-docs.mjs
- .github/workflows/docs.yml (CI link + frontmatter + structure gate)
- docs:check / docs:build / docs:dev scripts; blume 1.0.4 devDependency
- .gitignore: .blume/, /dist/, local agent logs
Moved (git mv, history preserved) into canonical structure:
- AUDIT.md -> docs/knowledge/security-audit.md
- docs/apply-agent-api.md -> docs/operations/runbooks/apply-agent-cli.md
- docs/production-smoke.md -> docs/operations/production-smoke.md
- docs/learning/new-things.md -> docs/knowledge/learnings/new-things.md
- docs/{plans,superpowers}/*, docs/PROJECT_RECOMMENDATION_CONTEXT.md,
docs/deploy-handoff.md, docs/README.md -> docs/archive/
Rewrote AGENTS.md as a concise bootloader (purpose, commands, critical
constraints, doc navigation, maintenance rules). Preserved the
FLEET-GUIDANCE block and shared fleet standard reference.
Validation: node scripts/check-docs.mjs passes (39 docs + 6 root md
files, 0 errors). pnpm lint introduces no new errors.
Generated with [Devin](https://devin.ai)
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e932ad4d36
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "wrangler": "^4.85.0", | ||
| "@biomejs/biome": "2.5.0" | ||
| "@biomejs/biome": "2.5.0", | ||
| "blume": "1.0.4" |
There was a problem hiding this comment.
This adds the blume dev dependency, but pnpm-lock.yaml is not updated in the same commit. The deploy and preview jobs run pnpm install --frozen-lockfile --ignore-scripts, and pnpm documents that --frozen-lockfile fails when the lockfile is out of sync with the manifest, so any PR preview or main deploy will fail at install before it can build or deploy.
Useful? React with 👍 / 👎.
| <a href="/jobs" class="hover:text-white transition-colors">Jobs</a> | ||
| <a href="/tools" class="hover:text-white transition-colors">Free Tools</a> | ||
| <a href="/pricing" class="hover:text-white transition-colors">Pricing</a> | ||
| <a href="/faq" class="hover:text-white transition-colors">FAQ</a> |
There was a problem hiding this comment.
In the production Worker deploy, wrangler.toml runs the Worker first for everything except /, and worker.mjs only serves the Astro asset binding directly for url.pathname === '/'; /faq is also absent from the Worker cacheable route list and there is no src/app/faq Next route. As a result, clicking this new /faq nav link in production falls through to OpenNext and 404s even though Astro copied faq/index.html into assets.
Useful? React with 👍 / 👎.
| - [App surfaces](product/surfaces.md) — every route and what it does. | ||
| - [STATUS.md](../STATUS.md) — short view: current objective, active work, blockers, next steps. | ||
| - [PROJECT_STATUS.md](../PROJECT_STATUS.md) — durable fleet-mandated status record (detail). | ||
| - [AGENTS.md](../AGENTS.md) — agent bootloader (commands, constraints, doc nav). |
There was a problem hiding this comment.
The new docs validator reports this as docs/index.md: broken link ../AGENTS.md because the repository contains agents.md with a lowercase name, not AGENTS.md. Since .github/workflows/docs.yml runs node scripts/check-docs.mjs on every push and pull request, the Docs workflow fails immediately until this link or filename is corrected.
Useful? React with 👍 / 👎.
1 participant
Consolidates the repository docs system with landing FAQ metadata and deployment guardrails. 425 tests pass locally.