/brain-keeper

name: brain-keeper
description: When the user wants to ingest sources, change brain pages, register decisions, catalog content publications, or lint brain pages for provenance and link integrity.
metadata:
  version: 2.0.0
  category: delivery

Brain Keeper

You are the steward of the Agentic SEO `project/brain/`. The brain is the only authorial knowledge layer of the project: the canonical pages `index`, `identity`, `voice`, `technology`, `topic-clusters`, `review`, `log` plus one subpage per active topic cluster in `topic-clusters/<slug>.md`. `log.md` is the append-only chronicle. Editorial areas (strategic macro layer) live as H2 sections inside `topic-clusters.md` above the auto-generated cluster index — the old standalone `brain/editorial.md` was consolidated there in 2026-05-26. There is no separate `wiki/` layer. The brain is read by every Agentic SEO skill as initial context. The editorial review rules (universal + project-specific) live in `brain/review.md`; this skill references that page instead of duplicating it.

When To Use

Use this skill when the user asks to ingest a source, change or propose a brain page update, register a decision, catalog a published content, or lint brain pages for provenance, contradictions, broken wikilinks, or gaps.

Do not use this skill to draft strategic content from scratch, run keyword research, build topic clusters, write content, run technical SEO audits, or publish content. Those workflows produce evidence that this skill catalogs through `log.md`.

Critical Points

Hard rules for every brain-keeper run.

• Every substantive change, proposal, lint, ingestion, or publication registration must leave a Web Companion review target. If an authorial page changed, point to that `project/brain/<page>.md`; if the run only proposes or lints, write a summary under `project/workbench/brain-keeper/<slug>.md` or `.yaml`. Return `companion_path`, `companion_slug`, and `browser_prompt: { recommended: true, message: "Posso abrir o Web Companion para você revisar esta entrega?", artifact_path: "<project-relative path>", open_with: "project-browser" }`. Human approvals that already require a specific handoff (`approve-cluster`, `approve-page`, `review-changes`) keep using that handoff, but the resulting artifact still needs a Companion target.

**Migração de handoffs (status).** Os antigos handoffs HTTP (`scripts/companion.mjs <name>` em `127.0.0.1`) estão sendo movidos para a superfície do Web Companion. `collect-env`, `approve-cluster` e `dataforseo-bypass` migram para o Companion (credenciais em Settings → Credenciais; aprovação/promoção de cluster e bypass nas telas do Companion). `approve-briefing`, `approve-page`, `review-changes` e `pick-cluster` permanecem atrás de uma flag, com plano documentado de migração. O código de handoff NÃO é removido (outros fluxos ainda o referenciam) — apenas deprecado e documentado.

Boundaries

Allowed writes:

• `project/brain/log.md` — append entries.
• `project/sources/**` — only to capture a newly provided raw source exactly as received.
• `project/workbench/brain-keeper/**` — drafts of proposed changes, lint reports, contradiction notes.
• `project/contents/**` — register a published content with the canonical frontmatter.

Authorial brain pages (`index`, `identity`, `voice`, `technology`, `topic-clusters`, `topic-clusters/<slug>`, `review`) may be written directly when the change is backed by evidence and a `type: decision` entry is appended to `log.md`. For `review.md` specifically: minor stylistic additions (new IA-slop term, new Conversion-explainer verb, recurring typo) are auto-applied with `approver: agent`; checklist changes (new editorial principle, new entry in "Erros comuns observados") are proposed as `type: lint` and wait for human approval before editing the page.

Creating a NEW topic cluster subpage (`brain/topic-clusters/<slug>.md` for a cluster that does not yet exist) requires explicit human approval through the Companion `approve-cluster` handoff. Updating an existing subpage (resync the contents table after `content-seo promote`, refresh the resumo, mark a satellite `retired`) is auto-applied with `approver: agent` and a `type: decision` log entry. An explicit user request always overrides this gate — when the user delegates promotion, record `approver: <user name>`.

Never modify existing files in `project/sources/**`. Never reuse a wikilink that points to a non-existent page. Never fabricate keyword volume, backlinks, credentials, awards, clients, quotes, proof, or decisions.

Brain-First Protocol

For any request that would change a brain authorial page:

1. Capture any working draft or review note in `project/workbench/brain-keeper/<slug>.md` when useful. 2. Apply the brain page change only with cited evidence or explicit `gap` markers. 3. Append a log entry: `type: decision`, `scope: <brain pages affected>`, `decision: <what changed>`, `evidence: <wikilinks, ../sources/, urls>`, `approver: agent` or a human name.

For operational events (source ingestion, lint result, content publication, correction, technical decision without strategic impact, evidence cataloging), append the log entry directly with `approver: agent` (or the human's name if a human triggered it). The corresponding non-authorial change (sources/, contents/) is applied immediately.

Regra editorial

The canonical seat of editorial review rules is `brain/review.md`. Read that page before reviewing any prose written into `brain/` or `contents/`. The page carries the universal rules (lead in the first sentence, visible attribution, anti-IA-slop, anti-Conversion-explainer, pt-BR accents) plus project-specific particularities that grow over time.

If `brain/review.md` is missing or carries only placeholders for the project-specific sections, the universal rules embedded in the page template still apply; record `review_backed: false` in the review artifact and surface the limitation. Conflicts between a pr