* docs: development docs match the codebase; add-a-provider playbook
- architecture.md: rewritten as a ~110-line map verified against the code
(processes, layout, data model from the migrations, graphs, model calls,
background jobs); links the accurate topic pages
- testing.md, api-reference.md, code-standards.md: rewritten from the real
suite, the /api prefix and Bearer auth, and the actual error-handling
pattern (no longer contradicts AGENTS.md)
- change-playbooks.md: new "Add an AI provider" playbook (registry + the four
hand-maintained copies + tests + docs, checked against #1443/#1444); fixes
async nodes, command registration, polling paths, locale steps
(LanguageToggle, satisfies TranslationShape), colocated frontend tests
- development-setup.md is the single setup page (deps, .env with localhost
SURREAL_URL, DB -> API -> worker -> frontend, real log lines, /health);
quick-start.md and README.dev.md point to it
- contributing.md: Conventional Commits, CHANGELOG rule, pre-PR checks that
match CI; PR template gains ruff format and frontend checks
- AGENTS files agree with the docs (provider edits, routers vs services,
async nodes, checkpoint path, ADR-013, stop_on); api/AGENTS.md is a plain
link instead of a Claude-only @ import
- ADR index explains ADR-010 (reserved for #1332) and number-at-merge;
GitHub-compatible encryption anchor; small credentials/security fixes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* docs: address review (CI commands, async source creation, paths, ADR-010, language toggle)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* style: apply ruff format to the Python codebase
Formatting only, no behaviour change: `uv run ruff format .` with the repo's
existing ruff 0.14.13 config. One `# type: ignore[arg-type]` in
open_notebook/graphs/ask.py moves onto the argument line the formatter split
out, so mypy keeps applying it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GBYpxzSS62Y3TZkgB9NUZy
* ci: fail the Backend Lint job on unformatted Python
Adds `ruff format --check .` after `ruff check .`, matching the existing
ruff-format pre-commit hook, and updates the docs that said formatting was
not gated yet.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GBYpxzSS62Y3TZkgB9NUZy
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* chore: add the oss-maintainer profile under .maintainer/
Scaffold `.maintainer/` (schema v1) so the oss-maintainer plugin can run
triage, release, review, process-discussions and smoke-e2e against this
repository: profile.toml, PROFILE.md, gotchas.md, triage.md,
release/runbook.md, release/test-matrix.md and smoke/journey.md.
The release runbook, test matrix, gates and the discussions rules move
here from the project-local `.claude/skills/{release,process-discussions}`
and the Codex mirror `.agents/skills/release`, which are removed so each
policy has one home. Commands stay referenced from AGENTS.md and the
Makefile; the human release process stays in .github/RELEASE_PROCESS.md.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ScFn54FhBq3cvVbcbQJjBZ
* chore(maintainer): address cubic review on the profile scaffold
- runbook: `uv sync --group dev` (dev is a dependency group, not an extra)
- smoke journey: the insight endpoint returns 202, not 200
- README/profile: state that commands are invoked in their CI form
(`ruff check .` without `--fix`), not re-implemented
- test-matrix: name the table's rows as Bucket A / C so the runbook's
"Bucket A" resolves
- drop the `.maintainer/ export-ignore` rule: the project ships Docker
images, not tarballs, and RELEASE_PROCESS.md points at the runbook
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ScFn54FhBq3cvVbcbQJjBZ
* chore(maintainer): finish the cubic follow-ups on the test matrix
- Backend suite row: `uv sync --group dev`, consistent with the runbook
- Bucket C is "the owner runs it by hand"; the Who / paid scope column,
not the bucket, says which rows need real credentials
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ScFn54FhBq3cvVbcbQJjBZ
---------
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
* docs: restructure documentation around AGENTS.md, VISION.md and decision 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)
* docs: fix README doc links and add markdown link check to CI
- 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
* docs: add documentation restructure to changelog
* feat: add cubic.yaml with project-aware AI review agents
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.
* docs: graduate issue-first policy by change size
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.
* docs: align PR template Related Issue section with graduated issue-first policy
* docs: address review — generalize ADR-002/004, unwrap hard-wrapped lines
- 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)
* fix: address cubic review — stale doc facts, make dev/full targets, link 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
