docs: restructure documentation around AGENTS.md, VISION.md and decision records

.github/RELEASE_PROCESS.md

@@ -36,6 +36,33 @@ version when the branch has enough validated change to ship.
    Docker Hub credentials are configured.
 7. Mark shipped issues with `released` and close any release-tracking tasks.
 
+## Docker Image Publishing
+
+The publishing workflow, from local test to promoted release:
+
+```bash
+make docker-build-local   # 1. Build for the current platform, test locally
+make docker-push          # 2. Push version tags (does NOT update latest)
+                          # 3. Test the pushed version in staging/production
+make docker-push-latest   # 4. Promote: push version + update v1-latest
+```
+
+| Command | What it does | Updates latest? |
+|---------|--------------|-----------------|
+| `make docker-build-local` | Build for current platform only (tags `<version>` + `local`) | No registry push |
+| `make docker-push` | Push version tags to registries | ❌ No |
+| `make docker-push-latest` | Push version + update `v1-latest` | ✅ Yes |
+| `make docker-release` | Full release (same as docker-push-latest) | ✅ Yes |
+| `make tag` | Create and push a git tag matching `pyproject.toml` | — |
+
+Publishing details:
+
+- **Platforms:** `linux/amd64`, `linux/arm64`
+- **Registries:** Docker Hub + GitHub Container Registry
+- **Image variants:** regular + single-container (`-single`)
+- **Version source:** `pyproject.toml`
+- Build issues: `docker builder prune`, then `make docker-buildx-reset`
+
 ## Manual Verification
 
 Before publishing a stable release, manually verify the areas touched by the

.github/pull_request_template.md

@@ -4,9 +4,11 @@
 
 ## Related Issue
 
-<!-- This PR should be linked to an approved issue. If not, please create an issue first. -->
+<!-- Non-trivial PRs (features, architecture changes) must link an approved issue.
+     Small obvious fixes (typo, docs, tiny bug) don't need one — write "N/A (small fix)" below.
+     Sizeable change without an issue? Mark this PR as draft and create the issue first. -->
 
-Fixes #<!-- issue number -->
+Fixes #<!-- issue number, or "N/A (small fix)" -->
 
 ## Type of Change
 
@@ -37,7 +39,7 @@ Fixes #<!-- issue number -->
 
 <!-- This section helps ensure your PR aligns with our project vision -->
 
-**Which design principles does this PR support?** (See [DESIGN_PRINCIPLES.md](../DESIGN_PRINCIPLES.md))
+**Which design principles does this PR support?** (See [VISION.md](https://github.com/lfnovo/open-notebook/blob/main/VISION.md))
 
 - [ ] Privacy First
 - [ ] Simplicity Over Features
@@ -96,9 +98,9 @@ Fixes #<!-- issue number -->
 
 Before submitting, please verify:
 
-- [ ] I have read [CONTRIBUTING.md](../CONTRIBUTING.md)
-- [ ] I have read [DESIGN_PRINCIPLES.md](../DESIGN_PRINCIPLES.md)
-- [ ] This PR addresses an approved issue that was assigned to me
+- [ ] I have read [CONTRIBUTING.md](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/contributing.md)
+- [ ] I have read [VISION.md](https://github.com/lfnovo/open-notebook/blob/main/VISION.md)
+- [ ] This PR addresses an approved issue assigned to me, **or** it's a small obvious fix (typo, docs, tiny bug) that doesn't need one — for anything bigger without an issue, mark this PR as draft and open the issue (triage takes 1–2 days)
 - [ ] I have not included unrelated changes in this PR
 - [ ] My PR title follows conventional commits format (e.g., "feat: add user authentication")
 

.github/workflows/docs-links.yml

@@ -0,0 +1,16 @@
+name: Docs Link Check
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+      - "scripts/check_md_links.py"
+      - ".github/workflows/docs-links.yml"
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check relative markdown links
+        run: python3 scripts/check_md_links.py

AGENTS.md

@@ -0,0 +1,54 @@
+# Open Notebook — Agent Rules
+
+Open Notebook is an open-source, privacy-focused alternative to Google's Notebook LM: an
+AI-powered research assistant with multi-provider AI support, fully self-hostable.
+
+This file holds the project-wide rules every coding session needs. Component rules:
+[open_notebook/AGENTS.md](open_notebook/AGENTS.md) (backend — also covers `api/`, `commands/`,
+`prompts/`) and [frontend/AGENTS.md](frontend/AGENTS.md). Knowledge lives in the docs (see
+[Where to look](#where-to-look)) — read it on demand instead of guessing.
+
+## Stack, ports, startup order
+
+Three tiers: Next.js frontend (3000) → FastAPI (5055) → SurrealDB (8000).
+
+Start in this order — each tier depends on the one below:
+
+1. `make database` — SurrealDB (API fails without it)
+2. `make api` — FastAPI; **schema migrations run automatically on startup** (check logs)
+3. `make worker-start` — surreal-commands worker. **Required**: podcasts, embeddings and source
+   processing are async jobs that silently queue forever without it
+4. `make frontend` — UI (depends on the API for all data)
+
+Or all at once: `make start-all` (status: `make status`, stop: `make stop-all`).
+
+## Commands
+
+- Tests: `uv run pytest tests/`
+- Python lint/typecheck: `ruff check . --fix` · `uv run python -m mypy .`
+- Frontend (inside `frontend/`): `npm run lint` · `npm run test` · `npm run build`
+- Docker release: `make docker-release` (see `.github/RELEASE_PROCESS.md`)
+
+## Hard rules
+
+- **Async-first**: every DB query, graph invocation and AI call is `await`-ed. No sync DB access.
+- **Never commit secrets.** Credentials are encrypted at rest and require
+  `OPEN_NOTEBOOK_ENCRYPTION_KEY` to be set.
+- CORS is wide-open and auth is a simple password middleware — **dev defaults, not production
+  hardening**. Don't build features that assume otherwise.
+- Product direction questions (does this feature fit?) → [VISION.md](VISION.md). Past decisions
+  ("why is it like this?") → [docs/7-DEVELOPMENT/decisions/](docs/7-DEVELOPMENT/decisions/).
+  Structural decisions made while coding should produce a new decision record there.
+
+## Where to look
+
+| Need | Location |
+|---|---|
+| Architecture (3 tiers, workflows, data model) | [docs/7-DEVELOPMENT/architecture.md](docs/7-DEVELOPMENT/architecture.md) |
+| Step-by-step recipes (add endpoint, migration, i18n…) | [docs/7-DEVELOPMENT/change-playbooks.md](docs/7-DEVELOPMENT/change-playbooks.md) |
+| Dev environment setup | [docs/7-DEVELOPMENT/development-setup.md](docs/7-DEVELOPMENT/development-setup.md) |
+| Code standards & testing | [docs/7-DEVELOPMENT/code-standards.md](docs/7-DEVELOPMENT/code-standards.md) · [testing.md](docs/7-DEVELOPMENT/testing.md) |
+| Product identity & current posture | [VISION.md](VISION.md) |
+| Decision log (ADRs/PDRs) | [docs/7-DEVELOPMENT/decisions/](docs/7-DEVELOPMENT/decisions/) |
+| Contribution process (issue-first, PRs) | [docs/7-DEVELOPMENT/contributing.md](docs/7-DEVELOPMENT/contributing.md) |
+| User/operator docs (install, configure, troubleshoot) | [docs/](docs/index.md) |

CHANGELOG.md

@@ -8,6 +8,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- `VISION.md` — the product's source of truth in two layers: durable identity (what Open Notebook is and is not, core principles) and current posture (the phase we're in, directional constraints, and the horizon clusters under consideration)
+- Decision records at `docs/7-DEVELOPMENT/decisions/` — short, immutable ADRs/PDRs answering "why is it like this?", seeded with 4 retroactive ADRs (SurrealDB, Esperanto, Streamlit→Next.js, Surreal Commands) and 2 PDRs (single-user first, provider-agnostic core)
+- `AGENTS.md` files (root, `open_notebook/`, `frontend/`) with the normative rules for coding agents and humans — commands, hard rules, and gotchas not derivable from the code; `CLAUDE.md` files are now one-line pointers to them
+- Five new engineering docs pages under `docs/7-DEVELOPMENT/`: credentials, content processing, podcasts, prompts, and frontend architecture
+- Contribution guidelines for AI-assisted and agent-generated PRs in the contributing guide — the operator owns the PR, issue-first still applies, tests must have actually run
+- CI check for broken relative links in markdown (`scripts/check_md_links.py` + `docs-links` workflow on PRs touching `*.md`)
+- `cubic.yaml` — AI review settings as code: PR-contract instructions, three custom review agents (vision & principles alignment backed by `VISION.md`, known mechanical caveats, security & testability) and automatic ultrareviews for auth/credential/encryption/migration changes
 - Documented the flow-driven release process in `.github/RELEASE_PROCESS.md`, including the `ready` to `main` to stable release path, dev/stable image labels, and maintainer verification checklist (#938)
 - List view for the Notebooks page — a tile/list toggle in the header lets you switch between the visual card grid and a compact row layout (name, description, source/note counts, last updated) for easier scanning of large collections. The choice is remembered across reloads and translated across all 14 locales (#885)
 - Documented the `ESPERANTO_TTS_TIMEOUT` environment variable (default `300`s) in the environment reference; raise it for slow or self-hosted TTS providers so long podcast segments don't fail with a timeout (#937)
@@ -19,6 +26,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - "Refresh content" action on web-link sources — re-fetches the URL and re-embeds the source so its content stays current, available from the source card menu once processing has completed (translated across all 14 locales) (#259)
 
 ### Changed
+- Developer documentation restructured: 17 knowledge-heavy `CLAUDE.md` files consolidated into the 3 `AGENTS.md` + docs pages above; `README.dev.md` became a pointer after its unique content moved into `development-setup.md` (make-workflow matrix), `.github/RELEASE_PROCESS.md` (Docker publishing) and the change playbooks (add-a-language); the maintainer guide now carries the curated label taxonomy (state funnel, `area:` labels, consolidation rules)
+- Fixed stale developer docs while migrating: real migration path/format (`open_notebook/database/migrations/N.surrealql` + `AsyncMigrationManager` registration), provider count (17), locale list (7), and 9 README links that pointed at documentation pages that never existed
 - The API's listen interface in the Docker images is now configurable via a new `API_HOST` environment variable instead of a hardcoded `--host 0.0.0.0`. The default is unchanged (`0.0.0.0`); set `API_HOST=::` to serve IPv6/dual-stack environments (#985)
 - `docker-compose.yml` now sources the SurrealDB credentials from `SURREAL_USER` / `SURREAL_PASSWORD` (applied to both the database server and the app), defaulting to `root:root` so the zero-config quick start is unchanged. Set them in a `.env` file to use your own credentials before exposing the instance; `.env.example` and the compose file note this (#946)