mirror of
https://github.com/lfnovo/open-notebook.git
synced 2026-07-25 15:47:29 +00:00
b38c74cf29
* 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
6 KiB
6 KiB
Open Notebook — Vision & Principles
This document is the product's source of truth in two layers with different lifespans: Identity (durable — what Open Notebook is and refuses to be) and Current Posture (temporal — where we are in the journey and what's on the horizon). Triage and design decisions are evaluated against this document; the reasoning behind each rule lives in the decision records.
Identity
Open Notebook is a privacy-focused, self-hosted alternative to Google's Notebook LM that empowers users to:
- Own their research data — full control over where data lives and who can access it
- Choose their AI providers — any provider, or fully local models
- Customize their workflows — adapt the tool to different research needs
- Access their work anywhere — web UI, API, or integrations
What Open Notebook IS
- A research assistant for managing and understanding content
- A platform that connects various AI providers
- A privacy-first tool that keeps your data under your control
- An extensible system with APIs and customization options
What Open Notebook IS NOT
- A document editor (use Google Docs, Notion, etc.)
- A file storage system (use Dropbox, S3, etc.)
- A general-purpose chatbot (use ChatGPT, Claude, etc.)
- A replacement for your entire workflow (it's one tool in your toolkit)
Principles
Durable, normative rules. Each links to the decision record that established it.
| Principle | Rule |
|---|---|
| Privacy first | User data stays under user control by default. Self-hosted is the primary use case; no telemetry without opt-in; no hard dependency on specific cloud services. |
| Provider-agnostic core | The default is portable: features must work across the provider matrix. Adopting a provider-exclusive capability is allowed but is a deliberate decision that requires a PDR (PDR-002). |
| Simplicity over features | Easy to understand and use, even if it means fewer features. Sensible defaults; advanced options behind progressive disclosure. |
| API-first | Every capability is accessible via the REST API — the UI is a client, never the only door (ADR-003). |
| Extensibility through standards | Extension happens through well-defined interfaces (transformations, commands, prompt templates), not forks. |
| Async-first | Long-running operations never block the UI or the API (ADR-004). |
How we evaluate requests
A feature request that conflicts with the IS NOT list or a principle gets closed with a pointer here — kindly, and with the reasoning. A "no" protects the core value proposition; it's not a judgment of the idea. If a request keeps coming back and the principle starts to feel wrong, that's a signal to revisit the principle through a decision record — not to make a quiet exception.
Current Posture
Reviewed: 2026-07. This section is expected to change. Updating it is not a reversal — it's a phase change, recorded with a short PDR and an edit here.
The phase we're in: get the basics working well for everyone before expanding. Priority goes to making the core experience (sources, chat, search, notes, podcasts) solid across the full provider matrix and deployment surface, ahead of new product surfaces.
Directional constraints
Decisions about the future we haven't made yet — recorded as "which door to keep open":
- Single-user first, multi-user compatible. Open Notebook is a single-user tool today, but multi-user is under active consideration (#712). New features must not gratuitously preclude multi-user (schema, auth, data scoping) (PDR-001).
- Portable by default. Provider-exclusive capabilities (including paid-only ones) are on the table for the future — deliberately, via PDR, never by accident (PDR-002).
Horizon
The big clusters under consideration — direction, not roadmap; no dates. Each has an umbrella issue where the thinking happens:
| Cluster | What it is | Where |
|---|---|---|
| Platform v-next | SurrealDB v3 migration, possible frontend/backend Docker image split, possible Surreal Commands → Celery move — evaluated together as one coordinated breaking change | #372 · #378 · #381 |
| Multi-user | Deep platform redesign: auth, data scoping, what "multi-user" means for a self-hosted tool | #712 |
| Content modes & artifacts | The output side: generated artifacts, videos, explainers, presentations, mind maps — as one coherent product surface, not a pile of features | #203 |
| Agents operating Open Notebook | Role inversion via MCP: AI agents use Open Notebook on the user's behalf — the platform becomes the research memory of agents, not just a UI | #878 · #693 · #973 |
How this document changes
- Identity changes rarely and deliberately: a decision record marks the old rule as superseded, then this document is updated.
- Posture changes when the phase changes: a short PDR captures the why, the section above is edited, and the "Reviewed" stamp is bumped.
- Engineering practices (code standards, anti-patterns, decision framework) live in docs/7-DEVELOPMENT/design-principles.md.