Documentation¶
These pages are also published as a site at https://kon-rad.github.io/argo/, built from this folder on every change to main.
New here? Start with the onboarding path: ten short pages from "I have notes somewhere" to a private knowledge base with agents working in it. Want it running right now? getting-started.md. Want to know how it fits together before you change it? architecture.md.
Onboarding¶
| Page | Read it when |
|---|---|
| What you get, and what to borrow | You are deciding whether it fits, or want the patterns for your own notes, app or company without installing anything |
| Set up your vault | You want a vault and the app, step by step with a check after each step |
| Connect Claude Code | You want Claude Code working in the vault under the guard and the dev-log gate |
| Connect Hermes | You run Hermes and want it on the same rules |
| Connect another harness | You use Codex, Cursor, OpenCode, a cron script or your own agent |
| Connect servers and computers | You want a server behind a login, a laptop that uses it, several agent machines, a screen on the wall |
| Privacy | You want to know what stays on your machine, what leaves it and when |
| Configuration and secrets | You want to know where every setting and key lives, on each machine |
| Orchestrate agents | You want rules, skills, contracts, dev logs, a tracker and a board working together |
| Adapt it | You want a recipe for your notes, your codebase, your business or your startup |
Reference¶
| Doc | Read it when |
|---|---|
| getting-started.md | You want a vault and the app running on your laptop, from nothing |
| architecture.md | You want the big picture: engine vs. vault, the app, the index, the harness, where data flows |
| vault.md | You want to understand the vault template, secondbrain-vault, AGENTS.md, skills, and how to update the engine |
| configuration.md | You need a setting: every env variable and every secondbrain.json key |
| sync.md | You work in the vault from more than one computer, or a server runs agents in it, and want every checkout committed, pulled and pushed on a timer without losing a note or leaking a key |
| modules.md | You want an optional feature (tracker, org board, kanban board, map, TV, usage, voice, livestream, ring, agents, chat, uploads) |
| kanban-board.md | You want to use the board: the nine statuses, the three doors, every cli-board and cli-org task command, per-machine tokens, and the hermes kanban trap |
| board-design.md | You want the board's architecture before changing its code: the record and the lanes, the tables, the write path, the rollout |
| rag.md | You want to know how notes become searchable passages and how the chat answers from them: chunking, embedding, hybrid retrieval, reranking, providers |
| agent-memory.md | You run the org module's bots and want each one to keep a bounded memory of its own wakes, and to propose (never apply) changes to its own prompt or skills |
| summaries.md | You want every agent session summarized by a local model (with paid fallbacks), the facts it learned held for your approval, a digest for a stand-up, and quality checks you can run |
| agent-harness.md | You run Claude Code or Hermes in the vault and want to know what the guard and the dev-log gate do |
| agent-company.md | You want a company of named agents on a message board that wake for cards, DMs and mentions and report to you |
| deployment.md | You want the app on a server behind a login |
| privacy.md | You want to know how the engine stays free of personal data, and how to keep your fork that way |
| zen-runtime.md | You want the plan for running the bots on zen-agent instead of Claude Code headless and Hermes cron: rules and a Jev gate in front of every wake, DeepSeek V4 Flash on OpenRouter as the default, context as capped parts, every run and dollar on /usage |
| zen-agent.md | You want to run a roster persona headlessly on any model with the board and the knowledge base as tools: what zen-agent is, how to use it, its architecture and design, and how it compares to Claude Code, Hermes and pi |
| self-improvement.md | You want to see the proposal (not built yet) for a self-improving loop over the rules, skills, board, org, cron jobs and engine: traces, evaluation, memory, and a possible headless runtime of our own |
Also, in the repository:
app/README.md: the app's tech stack, search design and invariants.addons/tv-kiosk/README.md: a Raspberry Pi that shows the app on a TV.zen-agent/README.md: zen-agent, the minimal headless agent runtime (pi agent core) that runs a roster persona with skills, the board and the knowledge base as tools, under a budget, with a trace per run.CONTRIBUTING.md: how to send a change.AGENTS.md: the rules AI coding agents follow when they change this repo.
Working on the docs¶
The site is MkDocs with the Material theme; mkdocs.yml at the repository root holds the navigation. Preview locally with pip install mkdocs-material && mkdocs serve, and run mkdocs build --strict before you push: the docs workflow runs the same command on every pull request that touches docs/, and a broken link fails it. Links to files outside docs/ are written as full GitHub URLs so they work on the site as well as on GitHub.