/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`. Zero external dependencies (stdlib only, API calls via urllib).

Quick Reference: 5 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.py health` → fix → moc → decay | | **CREATE** | New knowledge card | Schema lookup → write file → 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` |

---

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:** `graph.py health` + `enforce.py` → target 90+/100

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 (daily graph maintenance)

**When to use:** Daily upkeep, after edits, or when health score drops. This is the most common workflow.

Decision Logic

1. Run `graph.py health <vault-dir>` → check score
2. If health < 90 → investigate:
   a. broken_links > 0  → `graph.py fix <vault-dir> --apply`
   b. orphans > 5       → connect orphans to hub files (see Workflow 4)
   c. desc_coverage < 70% → add descriptions to files missing them
3. Run `moc.py generate <vault-dir>` → regenerate indexes
4. Run `engine.py decay <vault-dir>` → recalculate relevance + tiers
5. Run `graph.py health <vault-dir>` → confirm improvement

Thresholds & Action Triggers

| Metric | Good | Action needed | |--------|------|---------------| | Health score | ≥90 | <90: investigate broken links, orphans | | Broken links | 0 | >0: `graph.py fix --apply` | | Orphan files | <5 | ≥5: connect to hubs (Workflow 4) | | Description coverage | ≥80% | <70%: add descriptions | | Stale cards (>90d) | <20% | >30%: `engine.py creative` to resurface |

Commands

uv run scripts/graph.py health <vault-dir>           # health check
uv run scripts/graph.py fix <vault-dir> --apply       # fix broken links
uv run scripts/moc.py generate <vault-dir>            # regenerate MOCs
uv run scripts/engine.py decay <vault-dir>            # decay cycle (Ebbinghaus)
uv run scripts/engine.py decay <vault-dir> --dry-run  # preview decay changes
uv run scripts/engine.py stats <vault-dir>            # tier distribution
uv run scripts/engine.py creative 5 <vault-dir>       # resurface forgotten cards

---

Workflow 3: CREATE (new card with immediate linking)

**When to use:** Creating any new vault card. Always link immediately — orphan cards are wasted knowledge.

Steps

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 domain

• Hub = `_index.md` or `MEMORY.md` of that domain

b. Find 2-3 sibling cards of same type+domain → add `[[links]]`

• `uv run scripts/graph.py backlinks <vault> <hub>` → find siblings
• Or: read vault-graph.json → filter nodes by type+domain

c. Run `uv run scripts/engine.py touch <new-file>` 5. **Verify checklist:**

• [ ] Hub linked?
• [ ] 2+ related cards found?
• [ ] description ≠ title repeat?
• [ ] tags: 2-5, lowercase, kebab-case?
• [ ] status ∈ schema enum?

Templates: `references/card-templates.md`

---

Workflow 4: SEARCH & LINK (find + strengthen connections)

**When to use:** Looking up information in the vault, or strengthening weak areas of the graph.

Navigation (Hub → Links → Target)

1. **Determine domain** from the topic (work, personal, research, etc. — whatever your schema defines) 2