| name | arc-maintaining-obsidian |
| description | Use when the user wants to create, query, audit, or initialize an Obsidian vault — saving notes/ideas/URLs into it ("save this" / "file this back" included), querying vault knowledge, auditing health (missing links, orphans, drift), ingesting files, or registering vaults. Not for Excalidraw diagrams — use arc-diagramming-obsidian. |
| argument-hint | help | ingest <url|text> [--batch] [--link] [--vault=<name>] | query <question> [--vault=<name>] | audit [link|lint|grow] [--vault=<name>] | init-vault <path> --name <name> [--preset=<minimal|llm-wiki|news|project-tracker>] | register <path> --name <name> [--default] | list-vaults | unregister <name> | set-default <name> |
arc-maintaining-obsidian
A vault interface: the skill resolves which Obsidian vault to operate on, reads that vault's paired contract (AGENTS.md runtime contract + SCHEMA.md domain schema), and dispatches the requested action. Different vaults serve different domains — wiki / news / project tracker / journal / etc. The skill stays domain-agnostic; presets bootstrap new vaults into a chosen domain.
The skill owns: vault resolution + registry, init-vault bootstrap workflow, generic ingest/query/audit pipelines, mechanical primitives (sha256 hashing, LINK/LINT/GROW algorithms, search routing). Each vault's AGENTS.md + SCHEMA.md owns: types, thresholds, taxonomy, language policy, citation rules.
Mode Selection
Three universal vault actions. Pick from user intent:
| User Intent | Mode | Pipeline |
|---|
| Create, save, capture, ingest, "file this back" | ingest | Classify → Confirm → Create → Visuals → Index → Propagate → Log |
| Ask, search, "what do I know about", query | query | Orient → Search → Read → Synthesize → (File Back) |
| Audit, link, lint, grow, "check my vault" | audit | LINK → LINT → GROW |
Bare invocation (no mode argument, no clear intent) — do not ask "which mode?" blindly. Run Domain Contract Orientation first, then respond with what this vault is and what's available. See references/output-formats.md for the exact orientation response shape.
Only ask "ingest / query / audit?" when the user's intent words exist but are ambiguous (e.g., "I want to do something with my vault").
Help
If the argument is help, display this summary and stop:
arc-maintaining-obsidian — vault interface for Obsidian-based knowledge bases
REGISTRY-LEVEL (manage the vault registry; vault-agnostic):
help Print this help
list-vaults Show registered vaults
init-vault <path> --name <name> [--preset=<name>]
Bootstrap a new vault from a preset:
minimal | llm-wiki | news | project-tracker
register <path> --name <name> Register existing vault [--default sets default]
unregister <name> Remove from registry (files untouched)
set-default <name> Change default vault
VAULT-LEVEL (operate on a resolved vault; respect --vault=<name>):
ingest <url|text> [--batch] [--link] Create notes from sources
query <question> Search & synthesize from vault
audit [link|lint|grow] Vault health (LINK + LINT + GROW + vault-declared)
GLOBAL FLAG (any vault-level mode):
--vault=<name> Override vault auto-resolution
BARE INVOKE (no mode):
Run Domain Contract Orientation, then respond with what this vault is
(name, scope, declared types, last activity) and ask what to do.
Path Convention
All references/ and presets/ paths in this file are skill-relative. The Skill harness injects the absolute base directory at every invocation (look for Base directory for this skill: <abs-path> in your context). Construct absolute paths by prepending that base. The skill never relies on the user's CWD.
Mode Entry Gate
Every vault-level mode runs Domain Contract Orientation first, then loads the mode-specific mechanism reference. The gate is the unified jump table — references load on demand, not eagerly.
| Mode | Order |
|---|
| init-vault | Exception: read references/bootstrap-workflow.md first because no vault contract exists yet; that workflow authors the contract and registers via ${ARCFORGE_ROOT}/scripts/cli.js obsidian register. |
| Ingest | Resolve vault → read references/domain-contract-orientation.md → load references/page-templates.md for Raw Source / sha256 / extraction mechanisms if AGENTS.md adopts them → at the Visuals step, load references/visuals-decision-tree.md. |
| Query | Resolve vault → orientation → references/search-strategies.md for route selection and output adaptation. |
| Audit | Resolve vault → orientation → references/audit-checks.md for LINK / LINT / GROW mechanics; apply vault-declared domain policy from SCHEMA.md. |
| Any mode | First obsidian-cli call → load references/obsidian-cli-quirks.md once. End of mode → references/output-formats.md for completion / blocked templates. |
The references/ files describe mechanism; vault AGENTS.md + SCHEMA.md describe domain. The vault contract wins where they overlap.
Shared Context
Vault Resolution
The skill supports multiple registered vaults. Resolution cascades:
explicit --vault → active Obsidian → session cache → registry default → ask the user. Once resolved, the choice is sticky for the session. Read references/vault-resolution.md for the full cascade rules + first-run state + Obsidian-not-running fallback.
Domain Contract Orientation
Before any vault-level mode, read <vault>/AGENTS.md (runtime contract) and <vault>/SCHEMA.md (domain schema). Both are sticky for the session — re-read only on --reload-contract or mtime change. index.md and log.md (last 5 lines for orientation, last 30 for log audits) load on demand per mode. Missing AGENTS.md or SCHEMA.md blocks mutating modes (ingest / audit) with an explicit suggestion to run init-vault or author the contract manually. Read references/domain-contract-orientation.md for read-order details, sticky-session rules, and the missing-file matrix.
Registry Maintenance
The vault registry lives at ~/.arcforge/obsidian-vaults.json. The skill manages this file end-to-end through ${ARCFORGE_ROOT}/scripts/cli.js obsidian <subcommand> — never hand-edit, never construct JSON manually. Subcommands: register, unregister, set-default, list-vaults. The CLI applies first-becomes-default, atomic write, and file locking. Schema, behavior table, and rationale in references/registry-maintenance.md.
init-vault Bootstrap
When the user runs init-vault <path> --name <name> (with or without --preset=<name>), the skill drives an 11-step conversation: validate → pick preset → ask minimal questions → author AGENTS.md + SCHEMA.md from the preset (do not copy verbatim) → seed index/log → register via the CLI → advertise commands.
Read references/bootstrap-workflow.md before running any step. That file owns the full workflow including a worked example showing how "author from preset" plays out. Presets are one-shot authoring guidance, not stamping templates.
Available presets: minimal, llm-wiki, news, project-tracker. Each ships its paired starter under presets/<name>/AGENTS.md + presets/<name>/SCHEMA.md.
Vault Structure — Two Layers
Generic pattern (vault AGENTS.md / SCHEMA.md may extend or replace):
- Raw Sources (
Raw/ and format-specific folders) — Immutable originals when the vault adopts the Raw Source pattern. The LLM reads but never modifies these.
- Wiki / Domain Layer — Typed notes per the vault's SCHEMA.md.
When a Raw Source is ingested, the original stays where it is; a new typed note is created with source_url pointing back. Knowledge flows Raw → Wiki as text. See references/page-templates.md for the Raw Source frontmatter schema, sha256 hashing rule, extraction methods, and Paper URL chain.
Session Log
After every operation, append to <vault>/log.md:
## [YYYY-MM-DD] <operation> | <detail>
Operations: create | [type] | [filename], query | [question summary], audit | [scope], drift | [filename], init-vault | preset=<preset>. log.md is the contractual operation log; obsidian-cli daily:append is an optional best-effort dual-write — see references/obsidian-cli-quirks.md for plugin-detection rules and SIGPIPE caveat.
Delegation
Generic tool-routing table (filesystem baseline, optional QMD acceleration, optional Obsidian runtime, delegated diagram tools). Read references/delegation.md for the full routing table + first-search route selection + filesystem-as-contractual-baseline rationale.
Mode: Ingest
Classify → Confirm → Create → Visuals → Index → Propagate → Log
Per-step operational detail (Classify rules, Raw Source two-write protocol, Visuals decision tree, Propagate scope guard + contradiction detection, Special Modes — Query-as-Ingest / --batch / --link) is in references/mode-ingest.md. Read it before running any ingest. Pull in references/page-templates.md if the vault's AGENTS.md declares raw_source: adopted.
Key invariants:
- Write relationships as plain text, not wikilinks — audit LINK resolves them later. Honor language policy per AGENTS.md.
- Raw Source ingest is two distinct writes (immutable raw + typed wiki note with
sha256). Skipping the raw save loses re-extraction ability.
- Propagate caps at 10 related pages per ingest; surplus go to audit. Contradictions surface to the user, never silently overwritten.
- File-back / batch / link-on-create are documented behavioral variants of the same pipeline — see the reference for branching rules.
Mode: Query
Orient → Search → Read → Synthesize → (File Back)
Per-step detail in references/mode-query.md. Search route selection + output format adaptation in references/search-strategies.md.
Key invariants:
- Vault-only answers — including surrounding commentary. Never fall back to general knowledge in framing, insights, or comparisons. Name gaps explicitly so they feed audit GROW.
- Every key claim cites its source note inline
[[Like-This]]. Provenance follows sources: arrays.
- File Back triggers ingest internally (Query-as-Ingest, skip Classify) — same skill, no handoff. Always state your file-back decision: suggest, or explain why not.
Mode: Audit
LINK → LINT → GROW
Per-step detail in references/mode-audit.md. Mechanical primitives (schema compliance, orphan / untyped / tag checks, Source Drift via sha256, EVOLVE patterns, GROW Internal/External gap detection, vault-declared LINT extensibility) in references/audit-checks.md.
Key invariants:
- Only LINK modifies existing notes. LINT and GROW never modify.
- Verify before fix. LINT findings are hypotheses; read the actual file before acting (common false positive: YAML multi-line lists look empty to extractors but contain indented values).
- Never create stub entity notes without source backing. Broken wikilink resolution: has Raw Source → create via ingest; 3+ refs no source → flag for user; 1–2 refs no source → convert to plain text.
- Vault SCHEMA.md owns thresholds; the skill never invents numbers.
- Every audit run writes a typed report to
_audits/audit-YYYY-MM-DD-<scope>.md.
Output
Completion and blocked-message templates live in references/output-formats.md. Print verbatim with substitutions filled in so users scan many sessions quickly.
