---
name: agnoclast-author-docs
description: Push new/changed documentation (specs, plans, design docs) from disk into Agnoclast as authored wiki pages. Run after writing a spec/plan/design doc, when the user asks to sync docs to Agnoclast, or as part of session close-out.
---

> **Agnoclast-managed skill.** This file is installed and kept up to date by Agnoclast. Local edits are
> restored on the next session (a backup of your version is saved alongside). Don't rely on changes here.

## Why this exists

Specs, plans, and design docs get written to disk (a repo's `docs/`, skill-generated design docs)
and never reach Agnoclast — so the org brain misses its richest artifacts. A spec IS a page: this
skill turns pending docs into authored wiki pages. You (the live session) are the pipe — you read
the doc and author a synthesis. Never dump raw markdown into a page.

## When to use

- Right after you write or substantially update a spec/plan/design/runbook doc on disk.
- When the user asks to push/sync docs to Agnoclast.
- During session close-out (`/agnoclast-log` runs this as a sweep step).

## Steps

1. **Detect:** run `npx -y @theronap/cortex-mcp docs-scan --json`. If `pending` is empty, stop —
   report nothing. (If no roots are registered and you just wrote docs somewhere, suggest
   `docs-scan --add-root <dir>` to the user once; don't nag.)
2. **Triage each pending doc into exactly ONE of three dispositions.** Every pending doc gets one —
   there is no fourth "deal with it later" state:
   - **AUTHOR** it (below), then mark it.
   - **ABSORBED** — the doc is substantive, but an existing page *already covers it as well or
     better*. Common for build-notes and handoffs: the page kept getting updated while the doc
     stayed frozen at its writing date. Authoring it again would duplicate, or worse, overwrite a
     current page with a stale snapshot. **Mark it anyway** (`--mark`), and say which page absorbed
     it. Do NOT leave it unmarked: it is genuinely handled, and leaving it pending makes every
     future sweep re-read and re-litigate it. If the doc has one or two durable details the page
     lacks, add just those to the page, then mark.
   - **NON-SUBSTANTIVE** — scratch notes, generated output, throwaway logs. Leave unmarked and say
     so, so a human can decide whether it should be registered at all.

   ⚠ **A doc records the state at its writing date, never the state now.** Before writing any status
   claim into a page, verify it against the code — a build-notes doc saying "NOT built yet" is
   evidence about the past, not the present. Copying its status forward is the single most common way
   this skill injects a false claim into the wiki.

   To author:
   - Read the file. Decide the target node: a substantial standalone doc becomes its own
     project-kind node named by the doc's H1 title; a small note folds into its parent project's
     page as a section. Check the namespace first (`authoring_context`) — enrich an existing node
     rather than minting a synonym.
   - Call `author` with a distilled summary + sections — a synthesis of what the doc establishes
     (decisions, design, status), not a paste. Emit inline `[[links]]`: ALWAYS link up to the
     parent project node, plus related nodes; include the `[[repo:owner/name]]` stamp when the doc
     lives in a git repo (that joins the page to its commit timeline).
   - **Directionality is a hard rule:** the doc page links UP to the hub; NEVER author the hub
     page just to add a link back to a doc. Fan-in is queryable (`grep "[[hub]]"` = backlinks;
     `read_page history:true` = the node's event ledger) — hub pages stay curated prose, and a doc
     belongs on the hub only when a human-judged synthesis mentions it.
3. **Mark:** run `npx -y @theronap/cortex-mcp docs-scan --mark <path>` for every doc you AUTHORED or
   judged ABSORBED. Never mark a doc whose `author` failed — it must stay pending for the next sweep.
4. **Verify before reporting.** For each doc you claim you authored, confirm the write actually landed
   (`read_page` or `page_history`) — an `author` that returns "no change" when you intended an update
   did NOT land. Never report a page you did not confirm.
5. **Report:** one short block — each doc → the page it became, the page that absorbed it, or why it
   was left unmarked. The count of pending docs should be zero afterwards except for the
   non-substantive ones you deliberately left.

## Safety rules

- Do NOT register or sweep the local brain repo (`~/Documents/brain`) while the Robin parity soak
  is running — the experiment forbids re-syncing Robin into Agnoclast mid-window.
- Respect tiers: if a doc is clearly personal/sensitive, author it `confidential` or ask; default
  for work docs is the author path's normal default.
- This skill writes wiki pages via the `author` tool only. It never sends external messages and
  never deletes anything.