[automation] Sync SecondBrain framework (2026-W28)

.github/workflows/validate.yml

@@ -24,5 +24,9 @@ jobs:
         run: |
           vault="$(mktemp -d)"
           python3 install.py --vault "$vault"
+          test -f "$vault/skills/dtm/SKILL.md"
+          test -f "$vault/skills/voice/SKILL.md"
           python3 "$vault/tools/wiki.py" lint
           python3 "$vault/tools/dtm.py" lint
+          python3 "$vault/tools/documents.py" lint
+          python3 "$vault/tools/writing.py" lint

CONTRIBUTING.md

@@ -19,6 +19,8 @@ tmpdir="$(mktemp -d)"
 python3 install.py --vault "$tmpdir"
 python3 "$tmpdir/tools/wiki.py" lint
 python3 "$tmpdir/tools/dtm.py" lint
+python3 "$tmpdir/tools/documents.py" lint
+python3 "$tmpdir/tools/writing.py" lint
 ```
 
 Pull requests should explain the motivation, user impact, privacy implications,

README.md

@@ -6,7 +6,7 @@ deliberately separate LLM roles:
 - the **LLM Knowledge Agent**, which compiles curated sources into a persistent,
   cited wiki; and
 - the **Digital TeamMate (DTM)**, which maintains day-to-day continuity across
-  notes, tasks, projects, decisions, and follow-ups.
+  notes, tasks, projects, decisions, follow-ups, and authored work products.
 
 This repository contains only the reusable framework. It contains no personal
 vault data, source material, Daily Notes, project content, or activity history.

docs/installation.md

@@ -29,9 +29,31 @@ framework files with `--force` after reviewing the changes.
    `{{PLACEHOLDER}}`; never commit the resulting machine-specific values.
 5. Open the directory as an Obsidian vault.
 
+## Install the SecondBrain skills
+
+The vault installer keeps canonical skills under `skills/`. To make `$dtm` and
+`$voice` discoverable by Codex, copy them into the user's Codex skills
+directory:
+
+```sh
+mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
+cp -R skills/dtm "${CODEX_HOME:-$HOME/.codex}/skills/"
+cp -R skills/voice "${CODEX_HOME:-$HOME/.codex}/skills/"
+```
+
+Start a thread in the installed vault and invoke `$dtm`. That thread remains in
+DTM mode until `$end-dtm` or an explicit permanent switch to the Knowledge
+Agent.
+
+Invoke `$voice` after representative writing has reached `ready/` or
+`published/`, or after representative internal documents have reached
+`documents/final/`. It updates the private voice pack without analysing drafts.
+
 ## Validate
 
 ```sh
 python3 tools/wiki.py lint
 python3 tools/dtm.py lint
+python3 tools/documents.py lint
+python3 tools/writing.py lint
 ```

docs/operations.md

@@ -14,12 +14,38 @@ questions forward, instantiates enabled recurrence, captures decisions, and
 maintains project continuity. Durable knowledge can graduate to the wiki while
 remaining clearly distinguished from externally sourced evidence.
 
+## Internal documents
+
+Use `documents/drafts/` for collaborative internal drafting and
+`documents/final/` for the approved internal record of strategies,
+architectural notes, and similar work products. Use
+`documents/deliverables/<document-slug>/` for shareable `.pptx`, `.docx`,
+`.xlsx`, and similar artefacts linked to those documents. If a document also
+serves as a wiki source, keep the raw-source copy under `raw/` or
+`raw/processed/` as immutable provenance and manage the authored copy
+separately under `documents/`.
+
 ## Maintenance
 
 Run both structural linters after framework changes. Periodically perform a
 semantic wiki review for contradictions, stale claims, unsupported assertions,
 orphans, and evidence gaps.
 
+## Collaborative writing
+
+Writing moves from agent-assisted `drafts/` to the human-approved `ready/`
+queue and then to `published/` only after confirmed publication. Publishing
+integrations consume only content between explicit publish markers; private
+briefs, source checks, and revision notes remain in the vault. The framework
+includes a parameterized publisher definition but enables no destination by
+default.
+
+The explicit `$voice` skill learns only from reader-facing prose in
+`writing/ready/`, `writing/published/`, and `documents/final/`, maintains a
+private voice pack, and excludes drafts to avoid training the style guide on
+unfinished or agent-generated work. Drafting agents read the pack when present,
+while the current brief always takes precedence.
+
 ## Automation
 
 Definitions under `framework/automation-definitions/` are parameterized

docs/publication.md

@@ -20,6 +20,11 @@ the same export reuses the branch or existing pull request. If an earlier
 framework publication PR is still open, the run defers rather than creating a
 stack of noisy or competing reviews.
 
+Interactive agent sessions never publish directly. They may update and validate
+the live canonical framework, but must leave the external Git checkout and
+GitHub untouched. The scheduled weekly automation is the sole authorised
+promotion path.
+
 ## Review and promotion
 
 Review the generated PR with special attention to the privacy boundary,

examples/empty-vault/README.md

@@ -1,4 +1,6 @@
 # Empty SecondBrain vault example
 
 This directory contains sanitized seed scaffolding only. It contains no real
-Daily Notes, sources, projects, wiki knowledge, or activity history.
+Daily Notes, sources, projects, wiki knowledge, or activity history beyond a
+minimal root log setup entry required for structural lint to pass on a fresh
+install.

examples/empty-vault/documents/README.md

@@ -0,0 +1,4 @@
+# Internal documents workspace
+
+Managed internal documents live here. This public example contains no document
+content.

examples/empty-vault/documents/deliverables/README.md

@@ -0,0 +1,4 @@
+# Document deliverables
+
+Shareable internal document artefacts would live here in a real vault. This
+public example contains no deliverables.

examples/empty-vault/documents/drafts/.gitkeep

@@ -0,0 +1 @@
+

examples/empty-vault/documents/final/.gitkeep

@@ -0,0 +1 @@
+

examples/empty-vault/documents/index.md

@@ -0,0 +1,17 @@
+# Documents Index
+
+Curated catalogue of the collaborative internal-documents workspace. Add each
+managed draft, final document, and deliverable exactly once under its current
+lifecycle stage.
+
+## Drafts
+
+<!-- No draft documents yet. -->
+
+## Final
+
+<!-- No final documents yet. -->
+
+## Deliverables
+
+<!-- No document deliverables yet. -->

examples/empty-vault/log.md

@@ -0,0 +1,8 @@
+# SecondBrain Log
+
+Append-only history of SecondBrain operations. This sanitized seed starts with a
+single setup entry so lint can validate a fresh install cleanly.
+
+## [2026-01-01] setup | Empty vault scaffold
+
+Initialized the sanitized empty-vault example with no personal content, source material, Daily Notes, project state, or activity history.

examples/empty-vault/wiki/overview.md

@@ -14,4 +14,4 @@ tags:
 This is a deliberately empty, sanitized wiki seed. Add a source to `raw/` and
 ask the Knowledge Agent to ingest it.
 
-Browse [[wiki/index|Wiki Index]] or [[wiki/log|Wiki Log]].
+Browse [[wiki/index|Wiki Index]] or [[log|System Log]].

examples/empty-vault/writing/README.md

@@ -0,0 +1,6 @@
+# Writing workspace
+
+Collaborative drafts live in `drafts/`, explicitly approved publication items
+in `ready/`, and confirmed publication records in `published/`. This sanitized
+example contains no writing.
+

examples/empty-vault/writing/drafts/.gitkeep

@@ -0,0 +1 @@
+

examples/empty-vault/writing/index.md

@@ -0,0 +1,16 @@
+# Writing Index
+
+Every writing piece appears exactly once under its current lifecycle stage.
+
+## Drafts
+
+_No drafts yet._
+
+## Ready for publishing
+
+_No pieces ready for publishing._
+
+## Published
+
+_No published pieces yet._
+

examples/empty-vault/writing/log.md

@@ -0,0 +1,9 @@
+# Writing Log
+
+Append-only writing lifecycle history. This public seed contains no personal
+writing activity.
+
+## [1970-01-01] draft | Empty writing workspace initialized
+
+Created sanitized writing lifecycle scaffolding with no writing content.
+

examples/empty-vault/writing/published/.gitkeep

@@ -0,0 +1 @@
+

examples/empty-vault/writing/ready/.gitkeep

@@ -0,0 +1 @@
+

examples/empty-vault/writing/voice/voice-pack.md

@@ -0,0 +1,52 @@
+---
+title: Writing Voice Pack
+type: voice-pack
+status: provisional
+created: 1970-01-01
+updated: 1970-01-01
+ready_sources: 0
+published_sources: 0
+document_sources: 0
+tags:
+  - writing
+  - voice
+---
+
+# Writing Voice Pack
+
+## How to use this pack
+
+Apply observed patterns as flexible guidance. The current brief and direct user
+instructions take precedence.
+
+## Confidence and coverage
+
+This sanitized seed contains no voice evidence.
+
+## Declared preferences
+
+<!-- Human-owned. Voice analysis preserves this section verbatim. -->
+
+## Observed voice
+
+Insufficient evidence.
+
+## Avoid
+
+Insufficient evidence.
+
+## Context variations
+
+Insufficient evidence.
+
+## Drafting checklist
+
+- Follow the current brief before inferred tendencies.
+
+## Evidence ledger
+
+_No eligible sources analysed._
+
+## Change notes
+
+- 1970-01-01 — Created sanitized empty pack.