Frictionless docs — one-click links standard

Background

Spun out of Core/IT/Tasks/herdr-tabs.md round 6 (2026-08-24). Talbot wanted a link in herdr-workspace.md labeled “Edit herdr workspace” that opens the target file directly in NotePad++ (his default text editor) — like clicking a wikilink jumps to a note, or a URL opens a page. Round 6 confirmed the mechanism exists and is already installed: the obsidian-shellcommands plugin (.obsidian/plugins/obsidian-shellcommands, present in community-plugins.json, enabled) can define a named shell command and expose it as an obsidian://shellcommands/?id=<id> URI — droppable straight into a note as [Edit herdr workspace](obsidian://shellcommands/?id=<id>). Not yet configured — no data.json exists for the plugin, meaning zero commands have ever been defined in-app.

Talbot generalized past the single case: KB-OS should default to making all docs as frictionless to act on as to read — one-click links to launch an editor on a config file, one-click definitions for unclear acronyms/phrases, URI markdown links with filename params, links to external sites or local files — not just this one plugin. He explicitly flagged the scope question: is this a KB-OS mechanism (rollout/tooling) or an ai-config AGENTS.md authoring-standard addition (like the existing “define unfamiliar acronyms at first use” rule)? His read: likely both.

Tasks

• Resolve the standard-vs-mechanism split first (Talbot’s open question) — don’t build before this is settled:
  • Standard (what every doc should do, when): candidate addition to ~/ai-config/AGENTS.md, parallel to the existing acronym rule — one-click edit links for config/util files a doc describes, one-click definitions/links for unclear terms, favor URI/deep-links over prose “go open X and run Y.”
  • Mechanism (how it’s actually done): KB-OS rollout — configure obsidian-shellcommands entries, document the pattern (command naming convention, how to add a new one, how the resulting link is written) in a KB-OS reference doc.
• Configure the plugin for the concrete case that motivated this: a shell command that opens ~/utils/herdr-workspace.sh in NotePad++, exposed as a URI link, added to Core/IT/Utils/Custom/herdr-workspace.md.
• Verify the link actually launches NotePad++ on the file from inside Obsidian (don’t just confirm the plugin is enabled — click it).
• Write the “how to add a frictionless edit-link to any util note” pattern into a KB-OS doc (KB-OS-Usage.md or similar) so it’s repeatable without re-deriving the shellcommands setup each time.
• Decide (with Talbot) which other existing util notes get this treatment now vs. later — don’t sweep the whole vault in one pass; this task proves the pattern on one note.
• If an AGENTS.md standard addition is warranted, draft it and route through the normal ai-config edit (never edit deployed CLAUDE.md directly — edit ~/ai-config/AGENTS.md, per ai-config-agents-md-ssot memory).

Success Criteria

• Talbot can click a link in herdr-workspace.md and NotePad++ opens with herdr-workspace.sh loaded — verified live, not just “should work.”
• The pattern for adding another such link is documented somewhere findable (not just in this task file).
• The standard-vs-mechanism scope question is explicitly answered (not left implicit) — stated in the Claude Response that closes this out.

Context

• Triggering task: Core/IT/Tasks/herdr-tabs.md (round 6, 2026-08-24) — the concrete gap that surfaced this.
• Second confirmed motivating case: SDC/IT/Tasks/sdc-sdapp-pdf-reports.md (rounds 4-6, 2026-09-02) — Talbot needed one-click access to WSL .md files (repo STATUS.md/ROADMAP.md) from a Windows Obsidian KB task note, same underlying problem as herdr-workspace.md. Two Obsidian plugins were evaluated there (found only via a late close-time qmd search — this task existed the whole time and wasn’t found until then): External File Embed and Link — inline links open via the OS-default .md handler only (confirmed via its own GitHub docs, no in-Obsidian render setting), which on this machine flashes a terminal (Glow) and closes; its separate EmbedRelativeTo code-block does render inline in Obsidian but dumps the whole file’s content into the note, wrong shape for a short reference link. Markdown Anywhere — matches the desired click-to-open-in-Obsidian UX but ships a separate Windows companion .exe + creates vault symlinks, flagged but not installed (bigger footprint, wants a security look first). Neither was adopted; sdc-sdapp-pdf-reports shipped with plain WSL+Windows paths (copy-paste only) as the safe fallback. When this task executes, the obsidian-shellcommands URI mechanism should be evaluated against both these plugins for the general case, not just re-derived from scratch.
• Target file for the first live link: Core/IT/Utils/Custom/herdr-workspace.md.
• Existing precedent for a similar “authoring standard” addition to AGENTS.md: the “DEFINE UNFAMILIAR ACRONYMS AND TERMS AT FIRST USE” rule (added 2026-08-15, behavioural-solution-research task) — same shape (a doc-quality rule that improves comprehension/friction), good model for how a new rule gets worded and scoped (“applies going forward… do not retroactively sweep”).
• Core/CONSTITUTION.md — borrow > build, simplification-first (the plugin already does this; don’t build a custom mechanism).

Context (Auto-Prepared) — 2026-08-24

Resolved File Paths

• Core/IT/Utils/Custom/herdr-workspace.md → /mnt/d/FSS/KB/Core/IT/Utils/Custom/herdr-workspace.md (verified: exists — target for the first live link)
• .obsidian/plugins/obsidian-shellcommands/ → /mnt/d/FSS/KB/.obsidian/plugins/obsidian-shellcommands/ (verified: exists — main.js, manifest.json, styles.css; no data.json yet, meaning zero commands configured in-app so far)
• .obsidian/community-plugins.json → confirmed "obsidian-shellcommands" is listed (plugin enabled, not just present on disk)
• ~/ai-config/AGENTS.md → SSOT for any new authoring-standard rule (see ai-config-agents-md-ssot memory — never edit deployed ~/.claude/CLAUDE.md directly)
• Core/Processes/Projects/KB-OS/KB-OS-Usage.md → candidate home for the “how to add a frictionless link” pattern doc (not yet read/verified as the right file — check its existing structure before appending)

KB Context

• qmd search "one-click link edit file obsidian shellcommands frictionless docs" → no results at task-prep time. A later /task-complete herdr-tabs dup-check search (broader terms) surfaced Core/_WorkingOn/Later/Obsidian Executable Link Setup.md — an unprocessed Perplexity clipping already sitting in the vault, giving the exact URI syntax: Shell Commands plugin exposes its own direct URI (obsidian://shellcommands/execute?command=<name>, check plugin settings for “Copy URI”), no second plugin needed for that path. It also documents an Advanced URI-plugin route (obsidian://advanced-uri?vault=...&commandid=...) as an alternative if the direct URI proves unreliable — not installed in this vault (confirmed: absent from community-plugins.json and .obsidian/plugins/), only install if the simpler direct-URI route doesn’t work. Read this clipping first when starting execution — it has the concrete settings-UI steps (Add New Command, Shell: cmd, Working Directory, Copy Command ID/URI) this task’s own notes only described abstractly.
• herdr-tabs.md round 6 already confirmed the plugin is installed+enabled but never configured — this task starts from “define the first command,” not from “install the plugin.”
• Obsidian’s own file:// links open with the OS default handler for the extension, not necessarily the desired app — that’s why obsidian-shellcommands (which shells out to a named executable) is the right mechanism instead of a plain markdown/file link, per herdr-tabs.md round 6’s reasoning.

Dependencies

• Prerequisite status: all clear (prerequisites: none)
• External systems needed: none (Obsidian + already-installed plugin only)
• Files that must exist before execution: none beyond what’s already verified present above

Execution Notes

• Model recommendation: Sonnet — plugin configuration + doc-pattern writing, no architectural judgment large enough to need Opus.
• Assignee: claude
• Key constraints: don’t sweep other util notes with this pattern in the same task — prove it on herdr-workspace.md first, get Talbot’s confirmation the link actually works, then decide rollout scope as a follow-up. Don’t self-decide the AGENTS.md-vs-KB-OS split — Talbot flagged it as open; state a recommendation but don’t silently pick one and skip past it in the Claude Response.