/autograph

name: autograph
description: >-
  Schema-as-code enforcement for any Obsidian vault. Zero hardcoded domains.
  Use when creating vault cards, checking vault health, running schema compliance,
  deduplicating entities, generating MOC indexes, running decay cycles, bootstrapping
  a vault, fixing wikilinks, finding orphans or backlinks, extracting entities from
  daily files, or touching/promoting cards.
  Do NOT use for content generation or non-vault file operations.

autograph — typed vault engine

One schema. One graph. Works on any vault.

Overview

No hardcoded domains, types, or paths. The agent discovers structure from data, builds a schema, then enforces it. All scripts share `common.py`. Metadata uses PyYAML 6.0.3 (safe scalar loader); uv installs the declared dependency. API calls use urllib.

Quick Reference: 6 Workflows

| Workflow | When to use | Entry point | |----------|-------------|-------------| | **BOOTSTRAP** | New vault / after import / first setup | `discover.py` → `enforce.py` → `graph.py health` | | **HEALTH** | Daily maintenance / on request | graph + strict YAML checks → scoped repair manifest | | **CREATE / UPDATE** | New knowledge card, or new info about an existing one | `search.py` dedup → ADD/UPDATE/SUPERSEDE → link → touch | | **SEARCH & LINK** | Find info + strengthen connections | Hub → links → target; `graph.py orphans` → connect | | **ORCHESTRATE** | Automated multi-agent workflows (no API keys) | `orchestrate.py health\|bootstrap` | | **DAILY → CARDS** | Turn a day's raw notes into linked cards | `daily.py extract` → dedup-first process → link |

---

Workflow 1: BOOTSTRAP (raw vault → structured graph)

**When to use:** New vault, bulk import, first setup. Run once, then switch to HEALTH.

**Full guide:** `references/bootstrap-workflow.md`

Summary (10 phases)

1. **Discover:** `uv run scripts/discover.py <vault-dir> --verbose > /tmp/discovery.json` 2. **Generate schema:** Script baseline (`generate_schema.py`) + **agent swarm** (`swarm_prepare.py` → Wave 1 haiku → `swarm_reduce.py` → Wave 2 sonnet). **NEVER skip the swarm.** 3. **Review:** Human approves schema. Never auto-apply. 4. **Bootstrap + Enforce:** `engine.py init` + `enforce.py --apply` 5. **Link cleanup:** `link_cleanup.py --apply` (before enrichment) 6. **Tag enrich:** `enrich.py tags --apply` (via OpenRouter API) 7. **Deduplicate:** `dedup.py --apply` (before link enrichment) 8. **Link enrich:** `enrich.py swarm-links --apply` (**always swarm-links, never links**) 9. **MOC generation:** `moc.py generate` 10. **Verify:** `enforce.py --check` on the scoped manifest + `graph.py health` on the staged vault; resolve concrete validation/link findings. A health score is not an acceptance gate.

Critical Rules

• **Always run Phase 2B (agent swarm).** Script alone cannot classify unstructured content.
• **Always use `swarm-links`**, not `links` (0.3% vs 81.6% match rate).
• **Always dry-run first** — run without `--apply` before applying.
• **Dedup before link enrich** — prevents links to merged/trashed files.

---

Workflow 2: HEALTH (diagnosis before scoped repair)

Read [integrity.md](references/integrity.md) before maintenance or creating cards.

1. Build a staged view or run read-only checks. Use graph health for links and enforce --check for strict YAML/schema validation. 2. Separate missing targets, ambiguous links, no-incoming cards, isolated cards and reachability from hubs. Counts overlap; the health score is not an acceptance gate. 3. Inspect current sources and prepare an explicit file manifest. Preserve original bytes and body content for mechanical changes. Never infer a business state from an unknown status. 4. Apply only the reviewed repair scope. Do not mutate readonly archival paths. MOC generation preserves legacy/manual files unless an explicit managed block exists. 5. Recheck changed metadata and links, then publish the completed batch through the vault transport. Verify remote delivery separately.

The health orchestration command reports only; it does not automatically fix links, regenerate MOCs or change decay. Use uv run for all Python entry points so the declared YAML dependency is available.

Workflow 3: CREATE / UPDATE (dedup-first, then link)

**When to use:** Recording any card, or new information about something the vault may already track. Always look up first, always link immediately — a near-duplicate is the most common mistake; an orphan card is wasted knowledge.

Step 0: LOOKUP (mandatory — never skip)

uv run scripts/search.py "<entity / key phrase>" --vault <vault-dir> --json
# fallback: grep -ril "<name>" <vault-dir>

Pick the operation (full rules: `references/update-in-place.md`):

• **ADD** — no existing card → create it (steps 1–5 below).
• **NOOP** — already captured, unchanged → stop.
• **UPDATE** — same subject, new enrichment → open the card, sharpen `description`, append a dated line under `## Log`, re-`touch`.
• **SUPERSEDE** — new fact *contradicts* a current value → rewrite the current value (frontmatter field + top of description = "Compiled Truth"), move the OLD value to append-only `## History` (`- 2026-03→2026-06 · company: TDI Group`), set `updated:`. Whole card obsolete → `status: superseded` + `superseded_by: "[[new-card]]"`.

Only when the operation is **ADD**, continue:

Steps (ADD path)

1. **Type:** Pick from schema `node_types` 2. **Path:** Reverse-lookup `domain_inference` to find target folder:

   # domain_inference maps path→domain. To find folder for domain "crm":
   for path_prefix, domain in schema['domain_inference'].items():
       if domain == 'crm':
           target_folder = path_prefix  # e.g. "work/crm/"
           break

3. **Frontmatter:** Write description (search snippet, not title repeat), tags (2-5, lowercase, kebab-case), status from type's enum 4. **LINKING PROTOCOL (mandatory):** a. Add `## Related` section with `[[hub]]` file of the doma