diff --git a/ai-docs/log.md b/ai-docs/log.md index d107beb..b52c1be 100644 --- a/ai-docs/log.md +++ b/ai-docs/log.md @@ -21,3 +21,4 @@ Append-only. One line per operation: `## [YYYY-MM-DD] op | title` where op is on ## [2026-10-06] update | 0.3.0 (C-20261006-1): lint 5.2 s to 2.7 s on 3,124 files, --fix-index purpose clauses, --json honours --max (586 KB to 6.6 KB at --max 10), self-links no longer rescue orphans, SECURITY.md linked from README; tests/test_repo.py in CI and the release job; research pass with a forum sweep (R-20261006-1 to -3, m 0.4, next due 2026-10-20); eval action-1 1/1 (T-20261006-1) ## [2026-10-06] handoff | rewritten for 0.3.0 and the directory auto-publish check ## [2026-10-13] update | 0.4.0 (C-20261013-1), from the Claude Desktop marketplace test (the listed plugin run from a cloud chat linked to the owner's PC, asked to index the whole profile): unreadable files skipped and listed (was a PermissionError traceback), AppData/Application Data/Local Settings skipped by default (--include-appdata to opt in, owner's approval first), Windows hidden+system folders skipped (legacy profile junctions), --fix-index and --to-markdown-links refuse on a profile or >1,000 md files without --yes (exit 3), --root-index [--group] writes only the root INDEX.md, UTF-8 stdout; SKILL.md Step 1 adds the home-folder stop and a remote-session paragraph; L-005 to L-010; test cases 13a-13e; default lint of the profile completes (8 s warm, 4 locked scheduled-task files listed); branch fix/2026-10-13-desktop-test-gaps, PR left for the owner because master auto-publishes to the directory +## [2026-10-23] update | evergreen refresh (m 0.2, next due 2026-11-06): setup.md only (C-20261023-1): 1.14.5 security patch, 1.15 early-access CLI append/prepend under a heading, Windows CLI PATH answered (Obsidian.com redirector, restart the terminal), Update Relative Links plugin named for the move bug, obsidian-skills 50k stars; R-20261023-1 to -3; SKILL.md unchanged diff --git a/skills/obsidian-notes/CHANGELOG.md b/skills/obsidian-notes/CHANGELOG.md index 97a6bce..4311737 100644 --- a/skills/obsidian-notes/CHANGELOG.md +++ b/skills/obsidian-notes/CHANGELOG.md @@ -4,6 +4,11 @@ Every change to [SKILL.md](SKILL.md) and its companions, newest first, each with Entry shape: `### C-YYYYMMDD-n · date · one-line summary`, then `because:` (IDs or "user request"), `files:` (file and section), and a sentence on what changed. Cite section headings, not line numbers. +### C-20261023-1 · 2026-10-23 · setup.md: 1.14.5 and 1.15 notes, Windows PATH detail, Update Relative Links plugin, star count +- because: R-20261023-1, R-20261023-2 +- files: references/setup.md (Settings, "Automatically update internal links"; Opening a code repo as a vault; The official Obsidian CLI; Agent integrations table) +- Delta edits only; SKILL.md unchanged, so no test run was needed. + ### C-20261013-1 · 2026-10-13 · Safe on a user profile: unreadable files skipped, AppData skipped, bulk fixes guarded, `--root-index`, UTF-8 output, remote-session steps; version 0.4.0 - because: the Claude Desktop marketplace test of 2026-10-13 (the listed plugin run from a cloud chat linked to the owner's PC, asked for an index of the whole profile); L-005 to L-010 - files and what changed, one line per gap: diff --git a/skills/obsidian-notes/RESEARCH.md b/skills/obsidian-notes/RESEARCH.md index f82696c..9e45c04 100644 --- a/skills/obsidian-notes/RESEARCH.md +++ b/skills/obsidian-notes/RESEARCH.md @@ -2,22 +2,22 @@ Findings that back [SKILL.md](SKILL.md). Changes they caused are logged in [CHANGELOG.md](CHANGELOG.md); procedural lessons live in [LEARNINGS.md](LEARNINGS.md); test runs and their evidence in [TESTS.md](TESTS.md); schedule and state in `evergreen.json`. Protocol: [MAINTENANCE.md](MAINTENANCE.md). Setup detail for the user: [references/setup.md](references/setup.md). -Topic: Obsidian-compatible markdown for AI agents: link forms that work in Obsidian, GitHub and VS Code, index and map-of-content practice, the Obsidian CLI and agent integrations, vault layout. Tier `fast`. Last refresh 2026-10-06 (next due in `evergreen.json`). +Topic: Obsidian-compatible markdown for AI agents: link forms that work in Obsidian, GitHub and VS Code, index and map-of-content practice, the Obsidian CLI and agent integrations, vault layout. Tier `fast`. Last refresh 2026-10-23 (next due in `evergreen.json`). ## Current understanding Settled (high confidence, primary sources 2026-09-18): -- Obsidian treats `[[Note]]` and `[Note](Note.md)` as equivalent and documents turning `Use [[Wikilinks]]` off "to improve interoperability"; markdown links must be URL-encoded with forward slashes. GitHub does not render wikilinks (community discussion 73062 closed unanswered with no staff reply, re-checked 2026-10-06). So relative markdown links are the only form that works in Obsidian, GitHub and VS Code at once. "Shortest path" link format drops folders on rename when basenames collide (forum bug, January 2026); "relative" avoids it. +- Obsidian treats `[[Note]]` and `[Note](Note.md)` as equivalent and documents turning `Use [[Wikilinks]]` off "to improve interoperability"; markdown links must be URL-encoded with forward slashes. GitHub does not render wikilinks (community discussion 73062 closed unanswered with no staff reply, re-checked 2026-10-23). So relative markdown links are the only form that works in Obsidian, GitHub and VS Code at once. "Shortest path" link format drops folders on rename when basenames collide (forum bug, January 2026); "relative" avoids it. - The official Obsidian CLI shipped in 1.12.4 (2026-02-27), enabled in Settings > General and needing the 1.12.7 or newer installer; it remote-controls a running app (launches it if closed, not headless) and exposes search, read, create, append, links, backlinks, tags, properties, plugins, eval, screenshots. Obsidian's help says it exists so "agentic coding tools" can test and debug. -- kepano/obsidian-skills (49.2k stars, MIT; seven skills since knap on 2026-09-10, about 388k installs on skills.sh) is the de-facto official agent skill set. Its obsidian-markdown skill says to use wikilinks inside a vault and markdown links only for external URLs, so it assumes a vault-only reader; it does not cover GitHub compatibility or duplicate basenames. This skill takes the opposite rule (relative markdown links, an index per folder) and does not install or depend on obsidian-skills; it is recorded here as the main wikilink-first alternative. +- kepano/obsidian-skills (50.0k stars on 2026-10-23, MIT; six skills in the README since knap on 2026-09-10, no commits since 2026-09-15, about 388k installs on skills.sh) is the de-facto official agent skill set. Its obsidian-markdown skill says to use wikilinks inside a vault and markdown links only for external URLs, so it assumes a vault-only reader; it does not cover GitHub compatibility or duplicate basenames. This skill takes the opposite rule (relative markdown links, an index per folder) and does not install or depend on obsidian-skills; it is recorded here as the main wikilink-first alternative. - Obsidian has no AI features on its roadmap (May 2026 plugin platform relaunch; roadmap.md). Its AI posture is "open formats plus skills". - MCP access: the Local REST API plugin (2.9k stars) serves MCP itself since v5 (July 2026) at `https://127.0.0.1:27124/mcp/`; the mcp-obsidian bridge (4.4k stars) wraps the same API and has had no release since about May 2026. Claudian (15.4k stars, Obsidian 1.13+) embeds Claude Code and others inside Obsidian. - Practice: Karpathy's llm-wiki gist (April 2026) and its implementations (obsidian-mind 4.6k stars, claude-obsidian) converge on agent-maintained index and map-of-content notes, frontmatter with date, status and tags, a lint pass for dead links and orphans, and immutable raw sources. - Testing: headless linters exist (bborbe/obsidian-lint, vault-inspector, obsidian-broken-links-cleaner); the shared baseline is: every link resolves, no duplicate basenames, no orphans outside the index, frontmatter parses. No published eval suite for agent-written Obsidian notes was found; this skill's suite is its own. - One vault or many (forum thread 1445): split only when two trees have no sensible cross-links, need separate sync or privacy, or one is huge; the cost is lost cross-links, search and graph plus duplicated settings. Repo subfolders opened as vaults work with obsidian-git. -Contested or moving: whether the graph itself helps a reader (no measurement either way; testimony says lint and backlinks help, the picture does not); the CLI's headless story; files outside the vault (1.14 public since 2026-10-05: opens a single outside file and registers Obsidian in the OS "Open with" menu, the file's own links resolve from its folder; links from vault notes to outside files are still not documented as followable, so the skill's "link outside the root" warning stands, R-20261006-1); relative links inside a moved note are not updated by Obsidian (forum 4386, R-20261006-2); Obsidian Community capability disclosures for plugins (announced, rolling out). +Contested or moving: whether the graph itself helps a reader (no measurement either way; testimony says lint and backlinks help, the picture does not); the CLI's headless story; files outside the vault (1.14 public since 2026-10-05, 1.14.5 security patch 2026-10-22; 1.15.0 early access fixes outside-file rename and quick-switcher bugs but still says nothing on vault-to-outside links, R-20261023-1: opens a single outside file and registers Obsidian in the OS "Open with" menu, the file's own links resolve from its folder; links from vault notes to outside files are still not documented as followable, so the skill's "link outside the root" warning stands, R-20261006-1); relative links inside a moved note are not updated by Obsidian (forum 4386, R-20261006-2; plugins Consistent Attachments and Links and Update Relative Links work around it, R-20261023-2); Obsidian Community capability disclosures for plugins (announced, rolling out). ## Open questions @@ -25,7 +25,8 @@ Contested or moving: whether the graph itself helps a reader (no measurement eit - Will the CLI gain a headless mode? Partly answered 2026-09-18 (R-20260918-5): Obsidian Headless is a separate open-beta Sync client for servers and agents, not a headless desktop CLI; the CLI still needs the app. Watch whether Headless gains read and search commands. 2026-10-03: no change found (R-20261003-1); carried forward. - 1.14 is public (2026-10-05); can a vault note's markdown link to a file outside the vault be followed? The docs cover only links inside the outside file (R-20261006-1). Test by hand on an install. - Will Obsidian fix the relative-link-on-move bug (forum 4386)? (R-20261006-2) -- Does the `obsidian` shim land on PATH on Windows without a terminal restart, and what is its exact executable name (`Obsidian.com`)? Verify on a Windows install once the CLI is enabled. +- Resolved 2026-10-23 (R-20261023-1): the Windows shim is `Obsidian.com`, a redirector next to `Obsidian.exe`, added to the user PATH; it takes effect only after a terminal restart (obsidian.md/help/cli). +- What is the exact CLI syntax of 1.15's append or prepend under a heading? Not in the help page yet (R-20261023-1); check when 1.15 goes public. ## Search plan @@ -33,7 +34,7 @@ Four tracks; every refresh runs at least one query on each (scope each to the pe Subject (the goal and the latest thinking on reaching it): -- `site:obsidian.md/changelog ` and `site:obsidian.md/help cli` (CLI commands, link settings, roadmap) +- Fetch `https://obsidian.md/changelog/` and each per-release page directly (a web search for a version number returns only mirrors), plus `https://obsidian.md/help/cli` (CLI commands, link settings, roadmap) - `obsidian "use markdown links" OR "wikilinks" interoperability github ` and `github.com/orgs/community/discussions/73062` - `obsidian "one vault" OR "multiple vaults" forum` - `obsidian bases OR "json canvas" changelog ` @@ -41,7 +42,8 @@ Subject (the goal and the latest thinking on reaching it): Tooling (skills, plugins, MCP servers, scripts, knowledge graphs built for this subject): - `path:SKILL.md obsidian` on GitHub code search sorted by recently updated; `npx skills find obsidian`; skills.sh install counts for kepano/obsidian-skills (weekly, not all-time) -- `https://registry.modelcontextprotocol.io/v0/servers?search=obsidian`; `obsidian mcp server site:github.com ` (Local REST API plugin releases, mcp-obsidian, Claudian) +- `https://registry.modelcontextprotocol.io/v0/servers?search=obsidian` and `https://github.com/coddingtonbear/obsidian-local-rest-api/releases` directly (a `site:github.com` MCP search returns directory spam, 2026-10-23); mcp-obsidian, Claudian +- Plugins: `https://community.obsidian.md/plugins/` beats GitHub search for linters and link fixers; date obsidian-skills from its commits page - Practitioner test on each candidate: commit in the last 90 days, issues answered, author has other work in the area, ships evals - Provenance tiebreaker: prefer skills written by the latest frontier models at their highest reasoning setting when stated @@ -49,7 +51,7 @@ Practice (how people use agents on this goal): - `"claude code" obsidian vault workflow `; `karpathy llm-wiki obsidian`; `obsidian "map of content" agent ` - `"keep AI out of" obsidian` (the dissent, for balance) -- Forum sweep: `site:forum.obsidian.md` for links breaking on move or rename, AI agents writing notes, the CLI; r/ObsidianMD is rarely indexed (2026-10-06), so search the forum first. Old bugs still open are the useful finds. +- Forum sweep: `https://forum.obsidian.md/latest.json` (dated; `site:` search shows no dates) and `site:forum.obsidian.md` for links breaking on move or rename, AI agents writing notes, the CLI; r/ObsidianMD is rarely indexed (2026-10-06), so search the forum first. Old bugs still open are the useful finds. Testing (what proves the job was done): @@ -61,6 +63,24 @@ Testing (what proves the job was done): Newest first. Shape: `### R-YYYYMMDD-n · date · one line`, then `source:`, `track:`, `magnitude:` (major 0.6+ / real 0.3-0.5 / cosmetic under 0.3), `applied:`. +### R-20261023-1 · 2026-10-23 · Subject track: 1.14.5 public (Electron security update), 1.15.0 early access adds CLI/URI append or prepend under a heading; CLI facts re-confirmed, Windows PATH answered; GitHub 73062 unchanged +- source: https://obsidian.md/changelog/, https://obsidian.md/changelog/2026-10-22-desktop-v1.15.0/, https://obsidian.md/help/cli, https://github.com/orgs/community/discussions/73062 +- track: subject +- magnitude: cosmetic 0.15 +- applied: C-20261023-1 (setup.md vault-setup paragraph and CLI section). 1.15.0 also makes suggestions accent-insensitive and fixes two outside-file bugs (rename closed the tab; quick switcher could not create a note); no change to link resolution between vault notes, and vault-to-outside links still undocumented, so SKILL §Step 2's warning stands. The CLI still needs the running app and the 1.12.7+ installer; `unresolved`, `orphans`, `deadends` still listed. 73062: closed, unanswered, last comment 2026-08-13. + +### R-20261023-2 · 2026-10-23 · Tooling track: Update Relative Links plugin fixes links inside a moved note; obsidian-skills 50.0k stars, six skills, quiet since 2026-09-15 +- source: https://community.obsidian.md/plugins/update-relative-links, https://community.obsidian.md/plugins/better-markdown-links, https://github.com/kepano/obsidian-skills/commits/main +- track: tooling +- magnitude: cosmetic 0.2 +- applied: C-20261023-1 (setup.md "Automatically update internal links" line names it beside Consistent Attachments and Links; agent integrations table star count). Response: point. Update Relative Links 2.1.4, about 8k downloads, a vault-wide fix command, no release in about a year. Better Markdown Links is a third option, not named. MCP registry and skills.sh weekly installs not checked this pass. + +### R-20261023-3 · 2026-10-23 · Practice and testing tracks: quiet +- source: https://aident.ai/blog/claude-code-obsidian-without-losing-notes, https://code.claude.com/docs/en/plugin-evals.md, https://forum.obsidian.md/t/vault-inspector-find-broken-links-and-orphan-attachments/114637 +- track: practice, testing +- magnitude: cosmetic 0.05 +- applied: none. Practice: blog guides still install obsidian-skills to make Claude Code write wikilinks (the opposite rule, already recorded); they agree on index-first work and a root CLAUDE.md; no forum threads in the window. Testing: `claude plugin eval` unchanged (2.1.269+, six grader types, three runs against a baseline); its case files and skill-creator's `evals/evals.json` do not read each other, so mirroring means converting. Linters found (Vault Inspector 0.4.4, Link Doctor, Vault Link Check) are wikilink-first or in-app; none checks relative links or GitHub rendering. + ### R-20261006-1 · 2026-10-06 · Subject track: Obsidian 1.14 public (2026-10-05) opens outside markdown files; vault-to-outside links still undocumented - source: https://obsidian.md/changelog/2026-10-05-desktop-v1.14.4/, https://obsidian.md/changelog/ - track: subject diff --git a/skills/obsidian-notes/evergreen.json b/skills/obsidian-notes/evergreen.json index 775d741..2d21af9 100644 --- a/skills/obsidian-notes/evergreen.json +++ b/skills/obsidian-notes/evergreen.json @@ -14,8 +14,8 @@ "topic": "Obsidian-compatible markdown for AI agents: link forms that work in Obsidian, GitHub and VS Code, index and map-of-content practice, the Obsidian CLI and agent integrations, vault layout", "tier": "fast", "interval_days": 14.0, - "last_checked": "2026-10-06", - "next_due": "2026-10-20", + "last_checked": "2026-10-23", + "next_due": "2026-11-06", "verify_at_use": false, "volatile_claims": [], "contradiction": null, @@ -44,12 +44,18 @@ "m": 0.4, "interval_after": 14.0, "note": "user-requested pass with a forum sweep: Obsidian 1.14 public, relative links inside a moved note break (forum 4386), CLI unresolved/orphans/deadends, claude plugin eval; SKILL Step 2 and setup.md edited (C-20261006-1); cost: searches 11 · fetches 18 · tool calls 38" + }, + { + "date": "2026-10-23", + "m": 0.2, + "interval_after": 14.0, + "note": "quiet: 1.14.5 security patch, 1.15 EA CLI append/prepend under heading, Windows PATH answered, Update Relative Links plugin pointed, obsidian-skills 50k; setup.md only (C-20261023-1); cost: searches 5 · fetches 9 · tool calls 16" } ], "counts": { "learnings": 10, "changes": 10, - "research": 9, + "research": 10, "tests": 4 }, "consolidate_every": 25, diff --git a/skills/obsidian-notes/references/setup.md b/skills/obsidian-notes/references/setup.md index 8762400..b85d81f 100644 --- a/skills/obsidian-notes/references/setup.md +++ b/skills/obsidian-notes/references/setup.md @@ -8,7 +8,7 @@ Settings > Files and links: - `Use [[Wikilinks]]`: off. Obsidian then writes `[Note](path/Note.md)` when you link or drag a file, and still resolves existing wikilinks. - "New link format": Relative path to file. "Shortest path when possible" drops the folder and breaks on rename when two files share a name (forum bug, January 2026). -- "Automatically update internal links": on. It updates links that point to a moved note, but not the relative links inside the note that moved, so those break (forum thread 4386, open since 2022, still reported in 2026). Run `vault_lint.py` after moving notes; in the app, the Consistent Attachments and Links community plugin fixes them. +- "Automatically update internal links": on. It updates links that point to a moved note, but not the relative links inside the note that moved, so those break (forum thread 4386, open since 2022, still reported in 2026). Run `vault_lint.py` after moving notes; in the app, the Consistent Attachments and Links or Update Relative Links community plugins fix them (Update Relative Links also has a vault-wide fix command; no release in about a year). - "Excluded files": build and cache folders (`Library/`, `Temp/`, `obj/`, `Logs/`, `Builds/`, `node_modules/`). Obsidian hides them in search, graph view and unlinked mentions, and only deprioritizes them in the quick switcher and link suggestions. - "Show all file types" (older versions: "Detect all file extensions"; app.json `showUnsupportedFiles`): off, so a Unity or Node tree does not flood the file list. @@ -20,7 +20,7 @@ Commit `app.json`, `appearance.json`, `core-plugins.json`, `community-plugins.js ## Opening a code repo as a vault -"Open folder as vault" on the repo root gives one graph across `README.md`, `docs/`, `ai-docs/`, `CODEMAP.md`. Add the build folders to Excluded files first (above). Opening only `ai-docs/` as the vault is simpler but loses links to `docs/` and the README; a vault cannot span two sibling folders without their parent. Obsidian 1.14 (public 2026-10-05) opens single markdown files from outside any vault, with that file's own links resolved from its folder; whether a vault note's link to an outside file can be followed is not documented, so the lint still warns on it. +"Open folder as vault" on the repo root gives one graph across `README.md`, `docs/`, `ai-docs/`, `CODEMAP.md`. Add the build folders to Excluded files first (above). Opening only `ai-docs/` as the vault is simpler but loses links to `docs/` and the README; a vault cannot span two sibling folders without their parent. Obsidian 1.14 (public 2026-10-05; 1.14.5 on 2026-10-22 is an Electron security update, reinstall from the website) opens single markdown files from outside any vault, with that file's own links resolved from its folder; whether a vault note's link to an outside file can be followed is not documented, so the lint still warns on it. ## One vault or several @@ -30,13 +30,13 @@ For a set of separate repositories that should share one graph, either open thei ## The official Obsidian CLI (since 1.12.4, February 2026) -Needs the 1.12.7 or newer installer (Settings > General shows the installer version; if the toggle was on before an update, turn it off and on again). Enable: Settings > General > Command line interface, follow the prompt to register it, then restart the terminal. Windows adds `Obsidian.com` to PATH from the install folder; macOS symlinks `/usr/local/bin/obsidian`; Linux copies a binary to `~/.local/bin/obsidian`. The CLI remote-controls a running Obsidian and launches it when closed; it is not headless. Obsidian Headless (open beta, `npm install -g obsidian-headless`, command `ob`, Node 22+) is a separate Sync client that runs without the app but only syncs a vault; use `vault_lint.py` for headless checks. +Needs the 1.12.7 or newer installer (Settings > General shows the installer version; if the toggle was on before an update, turn it off and on again). Enable: Settings > General > Command line interface, follow the prompt to register it, then restart the terminal (the PATH change takes effect only in a new terminal). Windows adds `Obsidian.com`, a redirector next to `Obsidian.exe`, to the user PATH; macOS symlinks `/usr/local/bin/obsidian`; Linux copies a binary to `~/.local/bin/obsidian`. The CLI remote-controls a running Obsidian and launches it when closed; it is not headless. Obsidian Headless (open beta, `npm install -g obsidian-headless`, command `ob`, Node 22+) is a separate Sync client that runs without the app but only syncs a vault; use `vault_lint.py` for headless checks. ``` obsidian search query= path= limit= obsidian read file= obsidian create name= path= content= [template=] [overwrite] -obsidian append file= content= [inline] +obsidian append file= content= [inline] # also prepend; 1.15 (early access) adds append or prepend under a heading obsidian links file= [total] obsidian backlinks file= [counts] [format=json|tsv|csv] obsidian tags [file=] [counts] [sort=count] @@ -54,7 +54,7 @@ Use it for questions Obsidian answers better than a script (its own link resolut | Tool | What it is | When it is worth it | |---|---|---| -| kepano/obsidian-skills (49k stars; obsidian-markdown, obsidian-cli, obsidian-bases, json-canvas, defuddle, knap and others) | Official-author Agent Skills teaching the file grammars (Bases, JSON Canvas, callouts) | Not used by this skill: its obsidian-markdown skill prefers wikilinks and assumes a vault-only reader, the opposite of the relative-link rule here. Listed so you know it exists; nothing here depends on it | +| kepano/obsidian-skills (50k stars; obsidian-markdown, obsidian-cli, obsidian-bases, json-canvas, defuddle, knap and others) | Official-author Agent Skills teaching the file grammars (Bases, JSON Canvas, callouts) | Not used by this skill: its obsidian-markdown skill prefers wikilinks and assumes a vault-only reader, the opposite of the relative-link rule here. Listed so you know it exists; nothing here depends on it | | Obsidian CLI | Built into the app | Any live-vault question; free | | Local REST API plugin (2.9k stars, v5 serves MCP at `https://127.0.0.1:27124/mcp/`; 5.4.0 blocks `.obsidian/` by default, so write vault settings with `--vault-init` on disk) | HTTP and MCP access to a running vault | A long-running agent that edits the vault while Obsidian is open; the older mcp-obsidian bridge (4.4k stars, unmaintained since May 2026) wraps the same API | | Claudian (15k stars) | Claude Code, Codex and others as a sidebar inside Obsidian, vault as cwd | Working on notes inside Obsidian rather than from a terminal; desktop only, Obsidian 1.13+ |