baram2584/MultiPhysicsVault

Fork 0

Files

T

김경종 72dad72703

Tests / Hermetic test suite (push) Has been cancelled

Details

Tests / Skill frontmatter validation (push) Has been cancelled

Details

add claude-obsidian

2026-05-28 10:57:16 +09:00

18 KiB

Raw Blame History

type, title, created, updated, tags, status, related, sources

type

title

created

updated

claude-obsidian v1.4 Release Session

A complete release cycle covering v1.1, v1.4.0, and v1.4.1. Includes ecosystem research, external audit response, multi-agent compatibility rollout, full em-dash style cleanup, git history scrub for privacy, and a hotfix for the plugin install command syntax.

Release Sequence

Version	What shipped
v1.1	URL ingestion, image/vision ingestion, delta tracking manifest, 3 new skills (defuddle, obsidian-bases, obsidian-markdown), multi-depth wiki-query modes, PostToolUse auto-commit hook, removal of invalid `allowed-tools` frontmatter field
v1.4.0	Dataview to Bases migration, Canvas JSON 1.0 spec completeness, hooks hardening plus PostCompact, MCP setup hardened with Obsidian CLI option, custom callouts documented, 6 multi-agent bootstrap files, 249 em dashes scrubbed, security-rewrote git history to remove a placeholder email
v1.4.1	Hotfix for the wrong plugin install command syntax in README and docs/install-guide.md

v1.1: First Feature Release of This Session

Shipped in response to an internal quality check against the wider ecosystem (16+ Claude plus Obsidian projects researched, filed in claude-obsidian-ecosystem). The highest-value features from competing implementations were cherry-picked and shipped as v1.1.

New skills (Agent Skills spec compliant)

skills/defuddle/SKILL.md: strips ads, nav, and clutter from web pages before URL ingestion. Saves 40 to 60 percent on tokens for typical articles.
skills/obsidian-markdown/SKILL.md: full reference for Obsidian Flavored Markdown (wikilinks, embeds, all callout types, properties, math, Mermaid). Cross-references kepano/obsidian-skills as the authoritative source.
skills/obsidian-bases/SKILL.md: native Obsidian Bases .base file syntax. Uses correct filters/views/formulas structure (NOT Dataview-style from/where). Rewritten mid-session after the first attempt used the wrong syntax.

wiki-ingest upgrades

URL ingestion: passes any https:// URL directly. Uses WebFetch, optionally pipes through defuddle, saves to .raw/articles/, then runs the normal ingest pipeline.
Image/vision ingestion: .png, .jpg, .gif, .webp, etc. Claude reads the image natively, extracts text via OCR and concepts via vision, saves the description to .raw/images/, then ingests.
Delta tracking: .raw/.manifest.json tracks MD5 hash per source, timestamps, and the pages produced. Re-running ingest on unchanged files skips them automatically. Override with "force ingest".

wiki-query multi-depth modes

Three query tiers:

Quick (query quick: ...): hot.md plus index.md only. About 1,500 tokens. Best for fact lookups.
Standard (default): hot plus index plus 3 to 5 relevant pages. About 3,000 tokens. Best for most questions.
Deep (query deep: ...): full wiki cross-reference plus optional web search supplement. About 8,000+ tokens. Best for synthesis, comparisons, "tell me everything about X".

Hook: PostToolUse auto-commit

Every Write or Edit tool call to wiki/ or .raw/ triggers git add and git commit automatically. Guarded by [ -d .git ] so it never errors in non-git directories, and by git diff --cached --quiet so it never creates empty commits. Matcher: Write|Edit.

Critical fix: `allowed-tools` frontmatter removed

The Agent Skills spec only supports name, description, argument-hint, compatibility, disable-model-invocation, license, metadata, and user-invokable fields in SKILL.md frontmatter. The allowed-tools field was never valid and was being silently ignored. Removed from all 10 SKILL.md files to match the kepano/obsidian-skills authoritative convention.

v1.4.0: External Audit Response

External auditor delivered a 21-source review (the "compass artifact") against Agent Skills spec, Claude Code hooks, Obsidian v1.9 through v1.12, and JSON Canvas 1.0. Initial audit score: 6.5/10. Many findings were already resolved in v1.1 (the audit was conducted against a snapshot from before that release). The remaining valid findings became v1.4.0. Full findings and prioritization are in cherry-picks.

Tier 1: Critical fixes

Dataview to Bases migration (the biggest correctness fix). Obsidian Bases shipped as a core plugin in v1.9.10 (August 2025), providing native database-like views that replace Dataview for most use cases. Created wiki/meta/dashboard.base with six views (Recent Activity, Seed Pages, Entities Missing Sources, Open Questions, Comparisons, Sources). Updated wiki/meta/dashboard.md to embed the new base file as primary and keep the legacy Dataview queries as optional fallback. Reorganized README plugins section to recommend Bases (core, no install needed) as primary and mark Dataview as optional/legacy.

Canvas JSON 1.0 spec completeness. Added previously missing fields to skills/canvas/references/canvas-spec.md:

Group nodes: background (string path) and backgroundStyle (cover, ratio, repeat)
Edges: fromEnd (defaults to "none") and toEnd (defaults to "arrow"). Asymmetric defaults that produce a single arrow without explicit specification.
Documented the official hex ID convention alongside the descriptive ID alternative.

Tier 2: Important improvements

Hooks hardening plus PostCompact. hooks/hooks.json updated:

SessionStart now uses both command and prompt types. The command runs [ -f wiki/hot.md ] && cat wiki/hot.md || true as the canonical safety check that works in non-vault sessions without erroring. Matcher: startup|resume.
NEW PostCompact hook re-injects wiki/hot.md after context compaction. Critical insight: hook-injected context does NOT survive compaction, only CLAUDE.md does. Without this hook the hot cache disappears mid-session after any compact event.
PostToolUse auto-commit now guarded by [ -d .git ] in addition to the existing safeguards.
New hooks/README.md documents all four hooks plus the known plugin-hooks STDOUT bug (anthropics/claude-code#10875) and workarounds.

MCP setup hardened. skills/wiki/references/mcp-setup.md now has a > [!warning] callout above the NODE_TLS_REJECT_UNAUTHORIZED: "0" line explaining that it disables TLS verification process-wide (acceptable for 127.0.0.1 only). Added Option D: Obsidian CLI (Obsidian v1.12+) as the recommended alternative that avoids the TLS workaround entirely by using the native CLI via the Bash tool.

Custom callouts documented. The vault defines four custom callout types in .obsidian/snippets/vault-colors.css:

Callout	Color	Icon	Use for
`contradiction`	reddish-brown	`lucide-alert-triangle`	New source conflicts with existing claim
`gap`	beige	`lucide-help-circle`	Topic has no source yet
`key-insight`	bright blue	`lucide-lightbulb`	Important takeaway worth highlighting
`stale`	gray	`lucide-clock`	Claim may be outdated

Full documentation added to skills/wiki/references/css-snippets.md including built-in fallback equivalents for users who do not want the custom CSS. skills/wiki-ingest/SKILL.md got an explicit note that [!contradiction] depends on the CSS snippet.

Tier 3: Multi-agent compatibility (low complexity, high reach)

Skills are already in the cross-platform Agent Skills format. The only thing missing was adapter files so other AI coding agents could discover them. Added:

File	For
`AGENTS.md`	Codex CLI, OpenCode
`GEMINI.md`	Gemini CLI, Antigravity
`.cursor/rules/claude-obsidian.mdc`	Cursor (always-on rules)
`.windsurf/rules/claude-obsidian.md`	Windsurf Cascade
`.github/copilot-instructions.md`	GitHub Copilot
`bin/setup-multi-agent.sh`	Idempotent symlink installer that wires up `skills/` into each agent's expected location

This turns claude-obsidian into a multi-agent plugin at near-zero compatibility cost. Pattern borrowed from Ar9av-obsidian-wiki which was the reference implementation for multi-agent support.

Style Cleanup: Em Dash Scrub

Per user preference saved to feedback memory: never use em dashes (U+2014) or -- as punctuation. Use periods, commas, colons, or parentheses instead. Hyphens in compound words (auto-commit, multi-agent) are fine.

Wrote a context-aware Python scrubber at /tmp/scrub_em_dashes.py with rules:

Heading lines (^#): em dash becomes :
List items (^-, ^|): em dash becomes : (for label-description patterns)
Prose: em dash becomes . with next word capitalized

Result: 249 em dashes removed across 26 files. Scrubbed every SKILL.md, every doc, every hook file, every bootstrap file, and marketplace.json. Manual smoothing required for:

skills/obsidian-markdown/SKILL.md: 4 code-block annotation tables where the scrubber produced broken fragments. Converted to proper markdown tables.
skills/wiki-query/SKILL.md: 4 "If X. Respond." fragments rewritten as "If X, respond."
bin/setup-multi-agent.sh: 1 leftover em dash at end-of-line that the scrubber missed (only matched space-em-space). Plus one awkward echo string fixed.

The user-facing feedback was clear: "make it proper and natural". The scrubbed prose reads cleaner with the fragmented sentences smoothed out.

Security: Email Removal and Git History Rewrite

A placeholder email [scrubbed-email] (which the user confirmed does not exist as a real address) was in marketplace.json plus two docs. Removed from working tree first, then rewrote git history to scrub it from all commits.

Tool: git filter-repo (available at ~/.pyenv/versions/3.12.4/bin/git-filter-repo).

Two passes required:

git filter-repo --replace-text /tmp/email-replacements.txt --force scrubs blob contents across all commits.
git filter-repo --replace-message /tmp/email-msg-replacements.txt --force scrubs commit messages. The first pass caught 3 occurrences in file contents but missed 1 occurrence in a commit subject line. The second pass caught that.

Replacement string: [scrubbed-email]==>***REMOVED***

Post-rewrite actions:

Re-added the origin remote that filter-repo removes for safety
Moved v1.4.0 tag forward to include the security commit (since v1.4.0 had not been consumed yet by any user)
Force-pushed main plus both tags (v1.1 and v1.4.0)
Updated the v1.4.0 GitHub release notes to include a "Security Note" section

Verification: grep across all refs, all blobs, all commit messages returned zero matches for the scrubbed email string. GitHub release bodies checked for same: both v1.1 and v1.4.0 release pages clean.

Caveat for other clones: history rewrite means every commit hash changed. Any other machine or private community remote that has the repo still contains the old history. Those need git fetch && git reset --hard origin/main or a force push to clean up.

v1.4.1: Plugin Install Command Hotfix

The v1.4.0 README and install guide showed this install command:

claude plugin install github:AI-Marketing-Hub/claude-obsidian

This form does not exist in Claude Code. Users trying it see:

Failed to install plugin "github:AI-Marketing-Hub/claude-obsidian": Plugin "github:AI-Marketing-Hub/claude-obsidian" not found in any configured marketplace

The correct install flow (per `code.claude.com/docs/en/plugin-marketplaces`)

Plugin installation is a two-step process:

# Step 1: add the marketplace catalog
claude plugin marketplace add AI-Marketing-Hub/claude-obsidian

# Step 2: install the plugin from the catalog by name
claude plugin install claude-obsidian@claude-obsidian-marketplace

Where claude-obsidian is the plugin name (from plugin.json) and claude-obsidian-marketplace is the marketplace name (from marketplace.json). The @ delimiter separates them.

Why the confusion existed

There is no claude plugin install github:owner/repo shortcut. The marketplace abstraction is mandatory: Claude Code always fetches via a registered marketplace. A single-repo plugin like claude-obsidian is both the marketplace host and the plugin host, and the user must register the marketplace first before installing any plugin from it.

Command	What it does
`claude plugin marketplace list`	Show all registered marketplaces
`claude plugin marketplace add owner/repo`	Register a new marketplace from a GitHub repo
`claude plugin marketplace update <name>`	Refresh the marketplace catalog and re-clone
`claude plugin marketplace remove <name>`	Unregister a marketplace (also uninstalls its plugins)
`claude plugin install <plugin>@<marketplace>`	Install a specific plugin
`claude plugin list`	Show all installed plugins and their status
`claude plugin validate .`	Validate a marketplace.json, plugin.json, and frontmatter

Files changed in v1.4.1

README.md: Option 2 install section rewritten with two-step flow
docs/install-guide.md: same correction
.claude-plugin/plugin.json: 1.4.0 to 1.4.1
.claude-plugin/marketplace.json: both metadata.version and plugins[0].version bumped to 1.4.1

Confirmed working

After v1.4.1 was published, the user ran the corrected commands and saw:

claude-obsidian@claude-obsidian-marketplace
  Version: 1.4.1
  Scope: user
  Status: ✔ enabled

v1.4.1 installed at user scope and enabled.

Key Lessons (Worth Remembering)

Plugin install is always two-step. There is no github shorthand form. marketplace add then install plugin@marketplace.
allowed-tools is not a valid skill frontmatter field. The Agent Skills spec only accepts name, description, argument-hint, compatibility, disable-model-invocation, license, metadata, user-invokable. kepano/obsidian-skills uses only name and description which is the gold standard convention.
Obsidian Bases uses filters/views/formulas, not Dataview-style from/where. Easy to confuse. Always check help.obsidian.md/bases/syntax for the current syntax.
Canvas JSON 1.0 has asymmetric edge defaults. fromEnd defaults to "none", toEnd defaults to "arrow". Omitting both produces a single arrow pointing from source to target.
Hook-injected context does not survive context compaction. Only CLAUDE.md does. Any plugin that injects context via SessionStart hooks should also add a PostCompact hook to restore it mid-session.
git filter-repo needs two passes for full scrub. --replace-text handles blob contents, --replace-message handles commit messages. Running only one leaves traces.
git filter-repo removes the origin remote for safety. Must re-add it manually before force-pushing.
Marketplace name and plugin name can differ. Our marketplace is claude-obsidian-marketplace, our plugin is claude-obsidian. The @ delimiter disambiguates them.
Style preference: no em dashes anywhere. Periods, commas, colons, or parentheses instead. Applies to all prose, commit messages, release notes, file content. Hyphens in compound words are fine.

Files Created in This Session

Summary of everything new or newly created:

Path	Type	Purpose
`skills/defuddle/SKILL.md`	skill	Web page cleaner
`skills/obsidian-bases/SKILL.md`	skill	Obsidian Bases syntax
`skills/obsidian-markdown/SKILL.md`	skill	Full Obsidian syntax reference
`wiki/meta/dashboard.base`	bases dashboard	6-view Bases dashboard
`wiki/comparisons/claude-obsidian-ecosystem.md`	comparison	16+ project feature matrix
`wiki/concepts/cherry-picks.md`	concept	Prioritized feature backlog
`wiki/sources/claude-obsidian-ecosystem-research.md`	source	Research summary
`wiki/entities/Ar9av-obsidian-wiki.md`	entity	Multi-agent reference implementation
`wiki/entities/Nexus-claudesidian-mcp.md`	entity	Native Obsidian plugin
`wiki/entities/ballred-obsidian-claude-pkm.md`	entity	Goal cascade PKM
`wiki/entities/rvk7895-llm-knowledge-bases.md`	entity	Multi-depth query reference
`wiki/entities/kepano-obsidian-skills.md`	entity	Authoritative skill reference
`wiki/entities/Claudian-YishenTu.md`	entity	Native Obsidian plugin
`.raw/claude-obsidian-ecosystem-research.md`	raw source	Ecosystem research dump
`hooks/README.md`	doc	Hook documentation
`AGENTS.md`	bootstrap	Codex CLI / OpenCode
`GEMINI.md`	bootstrap	Gemini CLI / Antigravity
`.cursor/rules/claude-obsidian.mdc`	bootstrap	Cursor rules
`.windsurf/rules/claude-obsidian.md`	bootstrap	Windsurf Cascade
`.github/copilot-instructions.md`	bootstrap	GitHub Copilot
`bin/setup-multi-agent.sh`	script	Multi-agent symlink installer

Current Plugin State

Plugin installed: claude-obsidian@claude-obsidian-marketplace version 1.4.1, user scope, enabled
Releases on GitHub: v1.1, v1.4.0, v1.4.1
10 skills in skills/: wiki, wiki-ingest, wiki-query, wiki-lint, save, autoresearch, canvas, defuddle, obsidian-bases, obsidian-markdown
4 lifecycle hooks in hooks/hooks.json: SessionStart, PostCompact, PostToolUse, Stop
6 multi-agent bootstrap files covering Codex, OpenCode, Gemini, Cursor, Windsurf, GitHub Copilot
2 agents in agents/: wiki-ingest, wiki-lint

Deferred to v1.5.0

From the audit cherry-picks list, these items were identified but intentionally not included in v1.4.0:

/adopt command for importing existing vaults (medium complexity, adds new surface)
Vault graph analysis enhancement to wiki-lint (hub pages, cross-domain bridges, dead-ends)
Semantic search via qmd MCP server (optional external dependency)
Marp slide output from wiki queries (niche)
Thinking mode vs Writing mode UX experiment

18 KiB Raw Blame History