| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 8 | 0% |
| Commands | 0 | 0 | 2 | 0% |
| Section tags | 1 | 1 | 1 | 33% |
What each file covers
Sections
0 shared · 1 only in A · 8 only in B- − claude-obsidian
- + claude-obsidian: Agent Instructions
- + Product and vault boundaries
- + Bootstrap
- + Canonical skills
- + Mutation protocol
- + Vault conventions
- + Verification
- + Reference
Commands
0 shared · 0 only in A · 2 only in B- + python3 scripts/claude-obsidian.py init PATH
- + make test
Section tags
1 shared · 1 only in A · 1 only in B- − do-not
- + code-style
- agent-behaviour
Line diff
AgriciDaniel/claude-obsidian · .cursor/rules/claude-obsidian.mdc
@@ −1 @@
1---
2description: Portable rules for the claude-obsidian product and user vault workflows.
3globs:
4 - "skills/**/SKILL.md"
5 - "claude_obsidian/**/*.py"
6 - "wiki/**/*.md"
7 - ".raw/**/*"
8alwaysApply: true
9---
10
11# claude-obsidian
12
13Read `AGENTS.md` as the canonical contract. This repository is product source;
14mutable knowledge belongs in a separately resolved user vault.
15
16- Discover workflows from `skills/<name>/SKILL.md`.
17- Resolve vaults explicitly; never use the plugin/product directory by default.
18- Read a selected vault's bounded `wiki/hot.md` at session start when present.
19- Treat raw source payloads as create-only.
20- Have parallel workers draft; apply one recoverable operation transaction.
21- Keep queries and lint read-only. Put persistence or repair in a separate
22 reviewed operation.
23- Require consent for network egress, destructive changes, and Git checkpoints.
24
25Preview and then install workspace-local skill links with:
26
27```bash
28bash bin/setup-multi-agent.sh --host cursor --workspace "$PWD"
29bash bin/setup-multi-agent.sh --host cursor --workspace "$PWD" --apply
30```
31
32Public canonical: https://github.com/AgriciDaniel/claude-obsidian
33
AgriciDaniel/claude-obsidian · AGENTS.md
@@ +1 @@
1# claude-obsidian: Agent Instructions
2
3claude-obsidian is a local-first Agent Skills package for building source-cited,
4compounding Obsidian knowledge bases. It also ships a Claude Code plugin adapter.
5The portable workflow is implemented in `skills/` and the standard-library
6`claude_obsidian/` core; host hooks never define knowledge behavior.
7
8## Product and vault boundaries
9
10- This repository is the product source. It is not the default user vault.
11- A user vault is the directory containing `.claude-obsidian.json`, `wiki/`,
12 and `.raw/`. Mutable state always belongs there.
13- `templates/vault/` is the distributable seed. Root `wiki/`, `.raw/`, and
14 `.vault-meta/` are contributor state and are excluded from public artifacts.
15- Never derive a user vault from the plugin cache or `${CLAUDE_PLUGIN_ROOT}`.
16- A checkout containing contributor-vault state has no marketplace catalog.
17 `config/public-marketplace.json` is injected as
18 `.claude-plugin/marketplace.json` only inside the audited release artifact.
19 An extracted distribution-clean artifact may retain that exact manifest and
20 rebuild idempotently. A public default branch must be populated from the clean
21 artifact, never by pushing contributor-vault state.
22
23Resolve a vault in this order: explicit `--vault`,
24`CLAUDE_OBSIDIAN_VAULT`, nearest `.claude-obsidian.json`, then an unambiguous
25vault at or above the current directory. Fail closed when no vault is selected.
26
27## Bootstrap
28
291. Read this file. In a development checkout, also read the host-only root
30 `CLAUDE.md` when present; release artifacts intentionally omit it.
312. Read the selected skill completely.
323. Read only the references that skill routes to.
334. Resolve the user vault. If `wiki/hot.md` exists, read it silently.
345. For a new vault, run `python3 scripts/claude-obsidian.py init PATH` first;
35 apply only after reviewing the dry run. Use `adopt` for an existing vault.
36
37## Canonical skills
38
39All 15 skills live at `skills/<name>/SKILL.md`. They use the portable Agent
40Skills frontmatter subset: exactly `name` and `description`. Do not add mirrored
41files under `commands/`; Claude invokes plugin skills by namespaced names such
42as `/claude-obsidian:wiki`.
43
44Core workflows are `wiki`, `save`, `wiki-ingest`, `wiki-query`, and
45`wiki-lint`. Extensions are `autoresearch`, `canvas`, `defuddle`, `wiki-fold`,
46`wiki-mode`, `wiki-retrieve`, and `wiki-cli`. Reference skills are
47`obsidian-markdown`, `obsidian-bases`, and `think`.
48
49## Mutation protocol
50
51One logical knowledge operation is one recoverable transaction:
52
531. Read targets and record expected SHA-256 values.
542. Let parallel workers return drafts and evidence only.
553. Merge drafts into one `claude-obsidian.transaction.v1` bundle.
564. Inspect the bundle, then apply it once through `scripts/claude-obsidian.py`.
575. Report the operation ID and exact changed paths.
58
59Do not use direct shared writes, the deprecated `wiki-lock.sh` helper, or
60generic lifecycle auto-commits. Git checkpointing is separate and explicit.
61Raw source payloads are create-only; `.raw/.manifest.json` is the only mutable
62legacy raw metadata file. Destructive repairs, remote egress, and canonical
63research merges require explicit consent.
64
65## Vault conventions
66
67- `inbox/`: visible capture intake; never deleted automatically.
68- `.raw/`: immutable source payloads and legacy delta manifest.
69- `wiki/`: generated knowledge pages.
70- `wiki/meta/ledgers/`: source and claim provenance.
71- `wiki/hot.md`: bounded recent context, never a transcript.
72- `wiki/log.md`: operation history, newest first.
73- `.vault-meta/`: ignored runtime locks, journals, indexes, queues, and config.
74
75Use Obsidian Flavored Markdown: flat YAML properties, `YYYY-MM-DD` dates,
76wikilinks, embeds, and valid callouts. Never fabricate evidence locators,
77quotations, page numbers, or confidence.
78
79## Verification
80
81Run `make test` after behavioral changes. It executes every Python and shell
82suite plus the product, capability, package, hook, and manifest contracts.
83Public artifacts are built locally with `release build` and audited without
84publishing. No agent may push, tag, open or mutate issues, or publish a release
85without explicit owner approval.
86
87Claude SessionStart context injection is disabled by default. Treat
88`CLAUDE_OBSIDIAN_SESSION_CONTEXT=1` as explicit user consent to place bounded
89`wiki/hot.md` data in the model context; never set it automatically. A
90workspace-configured vault outside the project also requires an exact
91`CLAUDE_OBSIDIAN_SESSION_CONTEXT_VAULT` path.
92
93## Reference
94
95- Public canonical repository: https://github.com/AgriciDaniel/claude-obsidian
96- LLM Wiki pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
97- Obsidian primitives: https://github.com/kepano/obsidian-skills
98
@@ −1 +1 @@
1−---
2−description: Portable rules for the claude-obsidian product and user vault workflows.
3−globs:
4− - "skills/**/SKILL.md"
5− - "claude_obsidian/**/*.py"
6− - "wiki/**/*.md"
7− - ".raw/**/*"
8−alwaysApply: true
9−---
1+# claude-obsidian: Agent Instructions
102
11−# claude-obsidian
3+claude-obsidian is a local-first Agent Skills package for building source-cited,
4+compounding Obsidian knowledge bases. It also ships a Claude Code plugin adapter.
5+The portable workflow is implemented in `skills/` and the standard-library
6+`claude_obsidian/` core; host hooks never define knowledge behavior.
127
13−Read `AGENTS.md` as the canonical contract. This repository is product source;
14−mutable knowledge belongs in a separately resolved user vault.
8+## Product and vault boundaries
159
16−- Discover workflows from `skills/<name>/SKILL.md`.
17−- Resolve vaults explicitly; never use the plugin/product directory by default.
18−- Read a selected vault's bounded `wiki/hot.md` at session start when present.
19−- Treat raw source payloads as create-only.
20−- Have parallel workers draft; apply one recoverable operation transaction.
21−- Keep queries and lint read-only. Put persistence or repair in a separate
22− reviewed operation.
23−- Require consent for network egress, destructive changes, and Git checkpoints.
10+- This repository is the product source. It is not the default user vault.
11+- A user vault is the directory containing `.claude-obsidian.json`, `wiki/`,
12+ and `.raw/`. Mutable state always belongs there.
13+- `templates/vault/` is the distributable seed. Root `wiki/`, `.raw/`, and
14+ `.vault-meta/` are contributor state and are excluded from public artifacts.
15+- Never derive a user vault from the plugin cache or `${CLAUDE_PLUGIN_ROOT}`.
16+- A checkout containing contributor-vault state has no marketplace catalog.
17+ `config/public-marketplace.json` is injected as
18+ `.claude-plugin/marketplace.json` only inside the audited release artifact.
19+ An extracted distribution-clean artifact may retain that exact manifest and
20+ rebuild idempotently. A public default branch must be populated from the clean
21+ artifact, never by pushing contributor-vault state.
2422
25−Preview and then install workspace-local skill links with:
23+Resolve a vault in this order: explicit `--vault`,
24+`CLAUDE_OBSIDIAN_VAULT`, nearest `.claude-obsidian.json`, then an unambiguous
25+vault at or above the current directory. Fail closed when no vault is selected.
2626
27−```bash
28−bash bin/setup-multi-agent.sh --host cursor --workspace "$PWD"
29−bash bin/setup-multi-agent.sh --host cursor --workspace "$PWD" --apply
30−```
27+## Bootstrap
3128
32−Public canonical: https://github.com/AgriciDaniel/claude-obsidian
29+1. Read this file. In a development checkout, also read the host-only root
30+ `CLAUDE.md` when present; release artifacts intentionally omit it.
31+2. Read the selected skill completely.
32+3. Read only the references that skill routes to.
33+4. Resolve the user vault. If `wiki/hot.md` exists, read it silently.
34+5. For a new vault, run `python3 scripts/claude-obsidian.py init PATH` first;
35+ apply only after reviewing the dry run. Use `adopt` for an existing vault.
36+
37+## Canonical skills
38+
39+All 15 skills live at `skills/<name>/SKILL.md`. They use the portable Agent
40+Skills frontmatter subset: exactly `name` and `description`. Do not add mirrored
41+files under `commands/`; Claude invokes plugin skills by namespaced names such
42+as `/claude-obsidian:wiki`.
43+
44+Core workflows are `wiki`, `save`, `wiki-ingest`, `wiki-query`, and
45+`wiki-lint`. Extensions are `autoresearch`, `canvas`, `defuddle`, `wiki-fold`,
46+`wiki-mode`, `wiki-retrieve`, and `wiki-cli`. Reference skills are
47+`obsidian-markdown`, `obsidian-bases`, and `think`.
48+
49+## Mutation protocol
50+
51+One logical knowledge operation is one recoverable transaction:
52+
53+1. Read targets and record expected SHA-256 values.
54+2. Let parallel workers return drafts and evidence only.
55+3. Merge drafts into one `claude-obsidian.transaction.v1` bundle.
56+4. Inspect the bundle, then apply it once through `scripts/claude-obsidian.py`.
57+5. Report the operation ID and exact changed paths.
58+
59+Do not use direct shared writes, the deprecated `wiki-lock.sh` helper, or
60+generic lifecycle auto-commits. Git checkpointing is separate and explicit.
61+Raw source payloads are create-only; `.raw/.manifest.json` is the only mutable
62+legacy raw metadata file. Destructive repairs, remote egress, and canonical
63+research merges require explicit consent.
64+
65+## Vault conventions
66+
67+- `inbox/`: visible capture intake; never deleted automatically.
68+- `.raw/`: immutable source payloads and legacy delta manifest.
69+- `wiki/`: generated knowledge pages.
70+- `wiki/meta/ledgers/`: source and claim provenance.
71+- `wiki/hot.md`: bounded recent context, never a transcript.
72+- `wiki/log.md`: operation history, newest first.
73+- `.vault-meta/`: ignored runtime locks, journals, indexes, queues, and config.
74+
75+Use Obsidian Flavored Markdown: flat YAML properties, `YYYY-MM-DD` dates,
76+wikilinks, embeds, and valid callouts. Never fabricate evidence locators,
77+quotations, page numbers, or confidence.
78+
79+## Verification
80+
81+Run `make test` after behavioral changes. It executes every Python and shell
82+suite plus the product, capability, package, hook, and manifest contracts.
83+Public artifacts are built locally with `release build` and audited without
84+publishing. No agent may push, tag, open or mutate issues, or publish a release
85+without explicit owner approval.
86+
87+Claude SessionStart context injection is disabled by default. Treat
88+`CLAUDE_OBSIDIAN_SESSION_CONTEXT=1` as explicit user consent to place bounded
89+`wiki/hot.md` data in the model context; never set it automatically. A
90+workspace-configured vault outside the project also requires an exact
91+`CLAUDE_OBSIDIAN_SESSION_CONTEXT_VAULT` path.
92+
93+## Reference
94+
95+- Public canonical repository: https://github.com/AgriciDaniel/claude-obsidian
96+- LLM Wiki pattern: https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
97+- Obsidian primitives: https://github.com/kepano/obsidian-skills
3398
