mirror of https://github.com/lfnovo/open-notebook.git synced 2026-10-19 09:13:16 +00:00

chore: add the oss-maintainer profile under .maintainer/ (#1351 )

* 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>

2026-09-30 22:31:39 -03:00

3.1 KiB

Raw Blame History

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 (backend — also covers api/, commands/, prompts/) and frontend/AGENTS.md. Knowledge lives in the docs (see 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:

make database — SurrealDB (API fails without it)
make api — FastAPI; schema migrations run automatically on startup (check logs)
make worker-start — surreal-commands worker. Required: podcasts, embeddings and source processing are async jobs that silently queue forever without it
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. Past decisions ("why is it like this?") → docs/7-DEVELOPMENT/decisions/. Structural decisions made while coding should produce a new decision record there.
Maintainer profile lives in .maintainer/; do not run release, triage or discussions workflows without it.

Where to look

Need	Location
Architecture (3 tiers, workflows, data model)	docs/7-DEVELOPMENT/architecture.md
Step-by-step recipes (add endpoint, migration, i18n…)	docs/7-DEVELOPMENT/change-playbooks.md
Dev environment setup	docs/7-DEVELOPMENT/development-setup.md
Code standards & testing	docs/7-DEVELOPMENT/code-standards.md · testing.md
Product identity & current posture	VISION.md
Decision log (ADRs/PDRs)	docs/7-DEVELOPMENT/decisions/
Contribution process (Discussions → Issues → PRs)	docs/7-DEVELOPMENT/contributing.md
User/operator docs (install, configure, troubleshoot)	docs/