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.

Author: lfnovo

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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)

cubic.yaml

@@ -0,0 +1,78 @@
+# yaml-language-server: $schema=https://cubic.dev/schema/cubic-repository-config.schema.json
+#
+# cubic AI review settings (settings as code).
+# Docs: https://docs.cubic.dev/configure/cubic-yaml
+
+version: 1
+
+reviews:
+  custom_instructions: |
+    This project follows an issue-first workflow: every PR should reference an approved,
+    assigned issue and stay scoped to it. Unrelated refactors belong in separate PRs.
+    Test evidence must be real (actual output), especially for bug fixes, which should
+    include a regression test. Many PRs are agent-generated; hold them to the same bar.
+    Normative rules live in AGENTS.md (root, open_notebook/, frontend/); product direction
+    lives in VISION.md; past decisions in docs/7-DEVELOPMENT/decisions/.
+
+  custom_rules:
+    - name: Vision & principles alignment
+      description: |
+        Check the PR against the product identity and current posture defined in the
+        linked VISION.md. Flag:
+        - Features that gratuitously preclude multi-user (hard-coded single-tenancy in
+          schema, auth, or data scoping) — see PDR-001.
+        - Capabilities that only work on one AI provider without a PDR justifying the
+          exclusivity — the core is provider-agnostic by default (PDR-002).
+        - Features that conflict with the "What Open Notebook IS NOT" list.
+        - Structural/architectural decisions introduced without a decision record in
+          docs/7-DEVELOPMENT/decisions/ (half a page, same PR).
+      file_paths:
+        - VISION.md
+
+    - name: Known caveats
+      description: |
+        Enforce this project's recurring mechanical pitfalls (full rules in
+        open_notebook/AGENTS.md and frontend/AGENTS.md):
+        - i18n: every user-visible frontend string goes through t('section.key') and the
+          key must exist in ALL 7 locales (en-US, pt-BR, zh-CN, zh-TW, ja-JP, ru-RU, bn-IN).
+        - Providers: any change to supported providers must touch all 4 sync points:
+          api/models.py SupportedProvider, frontend ALL_PROVIDERS,
+          connection_tester.py TEST_MODELS, credentials_service.py PROVIDER_ENV_CONFIG.
+        - Migrations: a new open_notebook/database/migrations/N.surrealql file must also be
+          registered in AsyncMigrationManager (async_migrate.py) — no auto-discovery.
+        - Graphs: LLM calls in LangGraph nodes must use provision_langchain_model() and wrap
+          errors with classify_error(); model output goes through clean_thinking_content().
+        - Domain: Source.save() does not auto-embed — vectorize() must be called explicitly;
+          RecordModel singletons need clear_instance() in tests.
+        - Async jobs (podcasts, embeddings, source processing) run on the surreal-commands
+          worker; features depending on them must not assume inline execution. Permanent
+          failures raise ValueError (no retry); podcasts use max_attempts=1 by design.
+        - Frontend: FormData nested fields must be JSON.stringify-ed; don't re-add
+          Content-Type; check hasHydrated before rendering persisted Zustand state.
+
+    - name: Security & testability
+      description: |
+        Security:
+        - API endpoints must never return API key or secret values — metadata only.
+        - Every user-supplied URL must pass validate_url() (SSRF protection; private IPs are
+          intentionally allowed for self-hosted services).
+        - No secrets committed, logged, or echoed in error messages; credential fields use
+          SecretStr and Fernet encryption (OPEN_NOTEBOOK_ENCRYPTION_KEY).
+        - Raise typed exceptions from open_notebook.exceptions instead of bare HTTPException
+          or generic 500s.
+        Testability:
+        - Business logic belongs in services/domain, not in routers or React components,
+          so it can be tested directly.
+        - Critical paths (auth, credentials, encryption, migrations, data deletion) need
+          test coverage in the same PR.
+        - Bug fixes should include a test that reproduces the bug.
+
+  auto_ultrareview: custom
+  auto_ultrareview_custom_prompt: |
+    Run an ultrareview when the PR touches authentication, credential storage, encryption,
+    database migrations, or data deletion/cascade logic.
+  auto_ultrareview_file_patterns:
+    - 'open_notebook/database/migrations/**'
+    - '**/credential*'
+    - '**/auth*'
+    - '**/encryption*'