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

> **Cortex-managed skill.** This file is installed and kept up to date by Cortex. 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 Cortex — 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 Cortex.
- During session close-out (`/cortex-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. **Author each pending doc** (skip any you judge non-substantive — scratch notes, generated
   output; leave them unmarked and say so):
   - 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:** after each successful `author`, run
   `npx -y @theronap/cortex-mcp docs-scan --mark <path>`. Never mark a doc whose author failed —
   it should stay pending for the next sweep.
4. **Report:** one short block — each doc → the page it became (or why skipped).

## 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 Cortex 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.