AgriciDaniel/claude-obsidian / skills/wiki
wiki
VerifiedInitialize, adopt, and route work for a separate Obsidian knowledge vault through the portable claude-obsidian core. Use for vault setup, scaffolding, workspace selection, cross-project configuration, or choosing the correct wiki sub-skill. Triggers: /wiki, set up wiki, scaffold vault, create knowledge base, adopt this vault, Obsidian vault, second brain setup, persistent wiki.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| references/coordination.md | markdown | 1.9 KB |
| references/css-snippets.md | markdown | 4.3 KB |
| references/dataview.md | markdown | 1.6 KB |
| references/frontmatter.md | markdown | 2.7 KB |
| references/git-setup.md | markdown | 2.5 KB |
| references/install-modes.md | markdown | 1.9 KB |
| references/knowledge-recipes.md | markdown | 3.3 KB |
| references/mcp-setup.md | markdown | 1.9 KB |
| references/model-guidance.md | markdown | 1.6 KB |
| references/modes.md | markdown | 3.1 KB |
| references/operation-transactions.md | markdown | 6.0 KB |
| references/plugins.md | markdown | 2.7 KB |
| references/provenance.md | markdown | 3.2 KB |
| references/rest-api.md | markdown | 1.4 KB |
references/operation-transactions.md
View on GitHub# Operation transactions
Use this reference whenever a skill will change vault state.
## Contract
One logical operation produces one versioned transaction bundle and one
recoverable apply. Parallel workers may read and draft, but only the
orchestrator applies vault mutations.
Resolve the installed product root from the invoking skill's own location, not
from the user-vault working directory:
```bash
PRODUCT_ROOT=/absolute/path/to/installed/claude-obsidian
CORE="$PRODUCT_ROOT/scripts/claude-obsidian.py"
test -f "$CORE"
```
Never use the deprecated per-file `wiki-lock.sh` helper for new work. Never
commit from a generic lifecycle hook.
## Workflow
1. Resolve a user vault. Prefer `--vault`, then `CLAUDE_OBSIDIAN_VAULT`, then
`.claude-obsidian.json`, then unambiguous current-directory discovery.
2. Read every expected target and record its SHA-256, or `null` when it must be
absent.
3. Have workers return drafts and evidence. Workers do not edit shared vault
state.
4. Build one `claude-obsidian.transaction.v1` JSON bundle.
5. Run `python3 "$CORE" transaction inspect BUNDLE --vault VAULT`.
6. Show destructive, external, or canonical-merge proposals to the user before
applying them.
7. Pass the inspect result's exact `approval_sha256`, which binds the expanded
plan to the canonical resolved vault root and cannot be reused for another
vault:
`python3 "$CORE" transaction apply BUNDLE --vault VAULT --approved-plan-sha256 HASH`.
8. Report the resulting operation ID and changed paths.
9. If the user wants Git history, run the separate explicit checkpoint command.
## Bundle shape
```json
{
"schema": "claude-obsidian.transaction.v1",
"operation_id": "save-20260711-example",
"operation_type": "save",
"expected_hashes": {
"wiki/concepts/Example.md": null
},
"writes": [
{
"path": "wiki/concepts/Example.md",
"mode": "create",
"content_file": "drafts/example.md",
"sha256": "<sha256>"
}
],
"address_requests": [],
"source_manifest_updates": {}
}
```
`content` may replace `content_file` for small drafts. Use exactly one. Raw
source payloads are create-only. `.raw/.manifest.json` and the address counter
are expanded and journaled by the transaction engine when managed requests are
present. Only `ingest` and `autoresearch` own non-empty managed requests;
`setup` and `migration` may initialize the managed files directly. Other
operation types cannot target them.
Operation types are enforced authorities, not labels: `base` writes only
`wiki/**/*.base`; `canvas` writes canvases under `wiki/canvases/` and its
optional `_index.md`; `fold` writes exactly one `wiki/folds/*.md` page plus
`wiki/index.md` and `wiki/log.md`; `configuration` writes only
`.vault-meta/mode.json`; and `capture` creates only `.raw/captured/*` payloads.
Save, Markdown, lint repair, and generic extension bundles remain confined to
`wiki/`. `setup` and `migration` accept only the exact tracked vault-template,
ledger, and DragonScale bootstrap paths declared by the product contract; they
are not escape hatches for arbitrary root, plugin, snippet, metadata, or wiki
files. Paths that collide by case are rejected for macOS portability.
One content or predecessor file may be at most 64 MiB, and one operation's new
content or recovery backups may total at most 128 MiB. Split larger work at a
logical boundary before inspection; the engine rejects an operation it could
not roll back under the same limits.
One operation may contain at most 1,024 writes. Each canonical vault-relative
path may use at most 1,024 UTF-8 bytes. File-backed transaction bundles must be
no-follow regular files and may use at most 136 MiB; journals and completed
results are preflighted against the same 8 MiB cap used by recovery. These
limits ensure that every accepted operation remains readable and recoverable.
The lock retains the selected vault and `.vault-meta` directory descriptors
for the whole operation. Targets, journals, results, backups, capture queues,
checkpoints, and derived retrieval publications use no-follow descriptor-based
I/O, so replacing a public root, metadata, transaction, operation, or backup
entry cannot redirect reads, writes, rollback, or cleanup outside the selected
vault. This confinement requires POSIX directory descriptors and
`fcntl.flock`; Windows users must run the skill under WSL rather than native
Windows or Git Bash (setup and troubleshooting: `docs/windows-wsl.md`).
## Required coupled writes
- Save: note, index, log, hot cache.
- Ingest: source capture when applicable, pages, ingestion/evidence records,
indexes or MOCs, log, hot cache, and optional overview.
- Autoresearch: cited research pages and evidence records. Canonical merge is a
separate approved transaction.
- Fold: fold page, index, log.
- Canvas: canvas plus catalog metadata only when that metadata changes.
- Lint repair: approved fixes plus regenerated report/index.
- Query: read-only. Delegate persistence to Save.
## Failure behavior
- Exit 75 means the vault changed or another operation holds the mutation lock.
Re-read, rebuild, and inspect a new bundle.
- Validation failure means no vault write occurred.
- An interrupted apply is recovered or rolled back by the next apply, or by
`transaction recover`.
- Recovery never steals an old lock merely because its age elapsed. After
independently confirming that no writer is active, an operator may use
`transaction recover --force-stale-lock`; the same explicit override exists
for `capture queue recover`. Do not automate either override.
- Never paper over a transaction failure with `|| true`.
## Explicit checkpoint
```bash
python3 "$CORE" checkpoint OPERATION_ID --vault VAULT \
--as-of YYYY-MM-DD
```
Checkpointing is never automatic. It refuses all pre-existing staged state,
verifies the candidate tree's blob bytes against transaction hashes, runs
deterministic lint by default, and excludes raw source payloads unless the user
explicitly opts in. `--as-of` pins and records the UTC provenance audit date; a
pending record resumes the same commit and pinned date after interruption.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |