vrr/open-notebook
2
0
Fork 0
mirror of https://github.com/lfnovo/open-notebook.git synced 2026-08-31 10:34:22 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
open-notebook/docs/index.md
Luis Novo b38c74cf29
docs: restructure documentation around AGENTS.md, VISION.md and decision records (#1032) 
* 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
2026-07-10 15:33:19 -03:00

8.6 KiB
Raw Blame History

Open Notebook Documentation

Welcome to Open Notebook - a privacy-focused AI research assistant. This documentation is organized for different needs.

🎯 Choose Your Path

I'm brand new

→ Start here: 0-START-HERE

  • Learn what Open Notebook is
  • Pick your setup path (OpenAI, cloud, local/Ollama)
  • 5-minute quick start

I need to install/deploy

→ Go here: 1-INSTALLATION

  • Multiple installation routes
  • Docker Compose (recommended)
  • From source (developers)
  • Single container (deprecated, see Docker Compose)

I want to understand how it works

→ Read this: 2-CORE-CONCEPTS

  • Mental models and architecture
  • How RAG (retrieval-augmented generation) works
  • Notebooks, sources, and notes explained
  • Chat vs. transformations vs. podcasts

I want to use it (tutorials)

→ Follow this: 3-USER-GUIDE

  • How to add sources (PDFs, URLs, audio, video)
  • Creating and organizing notes
  • Chat effectively with your research
  • Creating podcasts from research
  • Search techniques

I need to configure it

→ Check this: 5-CONFIGURATION

  • Choose and setup AI provider
  • API configuration
  • Database setup
  • Advanced tuning

I need provider-specific help

→ Go here: 4-AI-PROVIDERS

  • OpenAI, Anthropic, Google, Groq, Ollama, Azure
  • Model comparisons
  • Cost estimates
  • Setup paths

Something's not working

→ Troubleshoot: 6-TROUBLESHOOTING

  • Quick fixes (top 10 issues)
  • Installation problems
  • Connection issues
  • AI/chat problems
  • Content processing issues
  • Podcast problems

I want to contribute/develop

→ Read this: 7-DEVELOPMENT

  • Architecture and tech stack
  • Contributing guidelines
  • API reference
  • Testing

📊 Documentation Overview

By Section

0-START-HERE — Entry point

  • What is Open Notebook?
  • Quick start guides (3 routes)
  • First 5 minutes

1-INSTALLATION — Getting it running

  • Multiple installation routes
  • Docker Compose (recommended), from-source
  • Requirements and setup

2-CORE-CONCEPTS — Understanding the system

  • Notebooks, sources, notes hierarchy
  • RAG (retrieval-augmented generation)
  • Chat, transformations, podcasts
  • Context management

3-USER-GUIDE — Using features

  • Adding sources (all types)
  • Working with notes
  • Chat effectively
  • Creating podcasts
  • Searching (text and semantic)

4-AI-PROVIDERS — AI configuration

  • Provider comparison
  • Setup for each provider
  • Model recommendations
  • Cost estimates

5-CONFIGURATION — Complete reference

  • AI provider setup (detailed)
  • Database configuration
  • Server/API settings
  • Advanced tuning
  • Environment variables (complete reference)

6-TROUBLESHOOTING — Problem solving

  • Quick fixes (top 10)
  • Installation issues
  • Connection problems
  • AI/chat issues
  • Content processing
  • Podcast generation
  • Getting help

7-DEVELOPMENT — For contributors

  • Architecture
  • Contributing guidelines
  • API reference
  • Testing & development

🔍 Find What You Need

By Problem Type

Installation & Setup

Using Open Notebook

Troubleshooting

Development

📚 Reading Paths

Path 1: Complete Beginner (1-2 hours)

  1. 0-START-HERE/index.md — Understand what it is
  2. 0-START-HERE Quick Start — Set it up
  3. 2-CORE-CONCEPTS/index.md — Understand concepts
  4. 3-USER-GUIDE/index.md — Learn features

Result: Fully understand how to use Open Notebook

Path 2: Get Running Fast (15 minutes)

  1. 0-START-HERE — Pick your path
  2. Follow quick-start guide for your setup
  3. Start using!

Result: Running in 15 minutes, learn details later

Path 3: DevOps/Deployment (1-2 hours)

  1. 1-INSTALLATION — Understand routes
  2. 5-CONFIGURATION — Reference setup
  3. 7-DEVELOPMENT - Architecture — Understand system

Result: Ready to deploy to production

Path 4: Troubleshooting (5-30 minutes)

  1. 6-TROUBLESHOOTING/index.md — Identify problem
  2. Find specific guide
  3. Follow solutions

Result: Problem solved!

❓ Common Questions

Q: Where do I start? A: → 0-START-HERE — Choose your setup path

Q: How do I install it? A: → 1-INSTALLATION — Multiple routes available

Q: How do I use [feature]? A: → 3-USER-GUIDE — Step-by-step tutorials

Q: Why does [feature] work like that? A: → 2-CORE-CONCEPTS — Understand the mental model

Q: How do I configure [provider]? A: → 4-AI-PROVIDERS or 5-CONFIGURATION

Q: Something's broken, what do I do? A: → 6-TROUBLESHOOTING — Problem solver

Q: How does the system work? A: → 2-CORE-CONCEPTS — Architecture and concepts

Q: Can I contribute? A: → 7-DEVELOPMENT — Contributing guide

📖 How This Documentation is Organized

Principles

  • Progressive Disclosure: Start simple, go deeper if needed
  • Multiple Entry Routes: Different paths for different users
  • High Signal-to-Noise: Focused content, no fluff
  • Step-by-Step: Clear instructions you can follow
  • Decision Trees: Help you pick the right path
  • Symptom-Based: Troubleshooting by what's broken

Structure

  • 0-START-HERE — Entry point (everyone starts here)
  • 1-INSTALLATION — Multiple setup routes
  • 2-CORE-CONCEPTS — Mental models (understand why)
  • 3-USER-GUIDE — How to use (step-by-step)
  • 4-AI-PROVIDERS — Provider guides
  • 5-CONFIGURATION — Reference material
  • 6-TROUBLESHOOTING — Problem solving
  • 7-DEVELOPMENT — For contributors

🚀 Quick Navigation

First Time?

→ START HERE

Just Want to Use It?

→ QUICK START (5 minutes)

Something Broken?

→ TROUBLESHOOTING

Full Reference?

→ CONFIGURATION

Developer?

→ DEVELOPMENT

📞 Getting Help

📈 Documentation Stats

  • 8 major sections
  • 35+ focused guides
  • ~80,000 words
  • Covers all features
  • Multiple entry paths
  • Progressive difficulty

🎯 Start Here

First time using Open Notebook? → Go to 0-START-HERE

Experienced, looking for specific help? → Use the navigation above to find your section

Something not working? → Go to TROUBLESHOOTING

Last updated: January 2026 | Open Notebook v1.2.4+