docs: restructure documentation around AGENTS.md, VISION.md and decision records - #1032
Merged
Conversation
…ion records - Consolidate 17 CLAUDE.md files into 3 AGENTS.md (root, backend, frontend); CLAUDE.md files become @AGENTS.md pointers - Add VISION.md: product identity + current posture with horizon clusters - Add docs/7-DEVELOPMENT/decisions/ with 4 retroactive ADRs and 2 PDRs - Add 5 new engineering docs pages (credentials, content-processing, podcasts, prompts, frontend) absorbing knowledge from removed CLAUDE.md - Dismember TRIAGE.md: label taxonomy into maintainer-guide.md, product jurisprudence into VISION.md, operator heuristics stay local (gitignored) - Add AI-assisted/agent-generated PR guidelines to contributing.md - Convert README.dev.md into a pointer after migrating its unique content (make workflow matrix, Docker publishing, add-a-language playbook) - Fix stale docs: migration path/format, provider count, locale list; fix broken links (docs/index.md, PR template, CONFIGURATION.md)
- Repoint 9 README links to pages that actually exist in docs/ - Replace literal (link) placeholder in maintainer-guide templates - Add scripts/check_md_links.py validating relative links in tracked markdown (skips URLs, anchors and code spans) - Add docs-links workflow running the check on PRs that touch markdown
Three custom review agents (vision & principles alignment backed by VISION.md, known mechanical caveats, security & testability), PR-contract review instructions, and automatic ultrareviews for auth, credential, encryption and migration changes.
Small obvious fixes (typos, docs, tiny bugs, i18n completions) no longer require an issue; features and architecture changes still do. Sizeable PRs opened without an issue convert to draft while the issue goes through triage (1-2 days). Applied consistently across contributing guide, root CONTRIBUTING pointer, PR template, maintainer guide red flags and cubic review instructions.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
All reported issues were addressed across 6 files (changes from recent commits).
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
lfnovo
commented
Jul 10, 2026
| @@ -0,0 +1,38 @@ | |||
| # ADR-002: Esperanto for multi-provider AI | |||
Owner
Author
There was a problem hiding this comment.
We should also mention content-core
Both follows the following rule: if this handles platform/media support and will probably require heavy coding, it doesn't belong in this project to keep it focused on the knowledge. Those parts can be replaced by other router frameworks if we decide to.
| @@ -0,0 +1,36 @@ | |||
| # ADR-004: Background jobs via Surreal Commands | |||
Owner
Author
There was a problem hiding this comment.
Should we really mention this since its probably being redesigned? What about mentioning the need for background workers instead? lots of content, different sizes of machines and servers, not locking the product usage while things happen, etc.
| Stores (src/lib/stores/) → API modules (src/lib/api/) → Backend | ||
| ``` | ||
|
|
||
| - **Pages** — route endpoints. Router groups `(auth)` / `(dashboard)` organize routes without |
Owner
Author
There was a problem hiding this comment.
why are there so many unnecessary new lines?
Contributor
There was a problem hiding this comment.
All reported issues were addressed
Confidence score: 5/5
- Safe to merge after the addressed issues were fixed.
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
- ADR-002 now records the general delegation rule (platform/media support that needs heavy coding lives in focused external libraries) covering Esperanto, Content Core and podcast-creator - ADR-004 now records the durable decision (long-running work runs on background workers — heavy content, varied machine sizes, never lock usage) with the queue technology as a swappable implementation detail pending #381 - Remove mid-paragraph hard line wrapping from authored docs to match repo convention (one line per paragraph)
…ink checker query strings - credentials.md: only PROVIDER_CONFIG exists as a map; Vertex/Azure/ OpenAI-compatible provisioning is inline in _provision_*() functions - content-processing.md: correct ContextConfig priority weights (source 100 > insight 75 > note 50) - development-setup.md + Makefile: make dev/full pointed at root compose files that don't exist; targets now use examples/docker-compose-dev.yml and examples/docker-compose-full-local.yml with --project-directory . - check_md_links.py: strip query strings before file-existence checks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Restructures the project's developer-facing documentation around three new artifacts — an
AGENTS.mdtree,VISION.md, and a decision log — and consolidates the redundant/stale material that had accumulated around them.The model: knowledge lives once, in the docs (pulled on demand); files that are auto-injected into coding-tool sessions carry only normative rules and pointers.
What changed
AGENTS.md as the canonical agent-context file
CLAUDE.mdfiles (~2,750 lines, largely restating code or duplicatingdocs/7-DEVELOPMENT/) consolidated into 3 content files: rootAGENTS.md(commands, startup order, hard rules),open_notebook/AGENTS.md(backend rules — also coversapi/,commands/,prompts/, with a one-line pointer atapi/AGENTS.md) andfrontend/AGENTS.mdCLAUDE.mdfiles are one-line@AGENTS.mdpointers, so the same content serves every toolsurreal-commandsworker requirement (async jobs silently queue without it) and the frontend npm commands — neither was written down anywhereVISION.md — product identity + current posture
Decision records (
docs/7-DEVELOPMENT/decisions/)Docs consolidation & fixes
TRIAGE.mdremoved: label taxonomy merged into the maintainer guide (reconciling the older conflicting taxonomy there), product jurisprudence into VISION.mdREADME.dev.mdbecame a pointer; its unique content moved todevelopment-setup.md,.github/RELEASE_PROCESS.mdand the change playbooksopen_notebook/database/migrations/N.surrealql+AsyncMigrationManagerregistration), provider count (17), locale list (7), 9 README links pointing at pages that never existed, brokenDESIGN_PRINCIPLES.mdreferences in the PR templateCI
scripts/check_md_links.py+docs-linksworkflow: validates relative markdown links on PRs touching*.md(skips URLs, anchors, code spans)Verification
uv run pytest tests/— 373 passed (only two comment-line changes in.pyfiles)python3 scripts/check_md_links.py— all relative links resolve (was 19 broken before, all pre-existing or fixed here)