Knowledge Workspace (Secondbrain)

The central knowledge repository is marcioaltoe/secondbrain: per-project mirrors, editorial notes, shared standards, and an LLM-maintained knowledge wiki (the second brain). Code repositories own their documentation as regular files; Secondbrain aggregates it automatically.

The contract

Documentation (CONTEXT.md, docs/ — specs, ADRs, task files, review artifacts) consists of regular files in the code repository. There is ONE commit flow:

• Edit docs and code together and commit together, in the same branch and PR. task_NN.md status flips and ## Result sections are ordinary repo commits — no second repository, no separate docs push.
• After every push to main (any merge type or direct push; never feature branches), GitHub Actions mirrors the paths listed in .secondbrain-export into secondbrain/projects/<project>/mirror/. This is automatic — never sync manually.
• The mirror is read-only. Never edit projects/<project>/mirror/ in secondbrain; the next sync overwrites it. Content worth editing belongs either in the code repo (project docs) or in secondbrain's editorial areas.
• Editorial areas are edited directly in secondbrain and pushed to its main: projects/<project>/notes/ (project notes that don't belong to the repo — meeting notes, era archives, client feedback) and shared/ (cross-project standards). registry/projects.json whitelists which repository may publish to which project.
• Consumption is one-way: nothing in secondbrain is ever written back to code repositories. To reference shared/ material from a repo, link to it — do not copy it in.

The export contract