smcllns · yolo-sam · May 15, 2026 · May 15, 2026
diff --git a/.agents/plans/2026-05-14-authoring-skill-release.md b/.agents/plans/2026-05-14-authoring-skill-release.md
@@ -3,7 +3,8 @@
 Scope:
 - [x] Sync `main` to merged PR #8.
 - [x] Rebase PR #7 branch onto theme-token work.
-- [x] Update canonical `.agents/SKILL.md` for real theme-token injection.
+- [x] Update canonical root `SKILL.md` for real theme-token injection.
+- [x] Keep `.agents/SKILL.md` as the local-agent mirror.
 - [x] Bundle `SKILL.md` into `dist/html-docs/` during build.
 - [x] Include bundled `SKILL.md` in release upload/provenance.
 - [x] Clarify README optional agent-skill install/discovery.
@@ -14,7 +15,8 @@ Scope:
 - [x] Add `skills.sh` install command to README.
 
 Decisions:
-- Plugin repo is canonical source.
+- Plugin repo root `SKILL.md` is the canonical source.
+- `.agents/SKILL.md` mirrors the canonical source for local agent discovery.
 - `smcllns/skills` is the installable mirror.
 - Obsidian plugin install does not install agent skills.
 - Plugin runtime must not write to agent install roots or dotfiles.

diff --git a/README.md b/README.md
@@ -15,48 +15,36 @@ A demo page (`test/fixture.html`) demonstrates all the passing HTML features.
 
 ![](demo.png)
 
-## Installation
+## Install Obsidian Plugin
 
-### Install from Obsidian directly
+* Install from Obsidian Community: [HTML Docs](https://community.obsidian.md/plugins/html-docs)
+* Build and install from source:
 
-* Go to Obsidian Community Plugins: [community.obsidian.md/plugins/html-docs](https://community.obsidian.md/plugins/html-docs)
-* Click Install
-
-### Install manually
-
-1. Download `main.js`, `manifest.json`, and `styles.css` from the [latest release](https://github.com/smcllns/obsidian-plugin-html-docs/releases/latest)
-2. Place those files into `<vault>/.obsidian/plugins/html-docs/`.
-3. Enable **HTML Docs** in Obsidian's Community Plugins settings.
-
-Releases are built and signed by GitHub Actions ([.github/workflows/release.yml](.github/workflows/release.yml)) so the binaries carry a [build attestation](https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations/using-artifact-attestations-to-establish-provenance-for-builds) you can verify against the source.
+```bash
+git clone https://github.com/smcllns/obsidian-plugin-html-docs/
+bun install
+bun run dev      # watch + rebuild
+bun run build    # production bundle at `dist/html-docs/`
+```
 
-### Optional Agent Skill
+### Download Agent Skill (optional)
 
 There is an optional agent skill so your agent can author HTML that fits this plugin's sandbox, theme tokens, assets, and embeds.
 
-- Skills CLI: `npx skills add smcllns/skills --skill obsidian-html-docs`
-- Manual: [smcllns/skills/skills/obsidian-html-docs/SKILL.md](https://github.com/smcllns/skills/blob/main/skills/obsidian-html-docs/SKILL.md)
-
-### Build and install from source
-
-```bash
-git clone https://github.com/smcllns/obsidian-plugin-html-docs/
-npm install
-npm run dev      # watch + rebuild
-npm run build    # production bundle at `dist/html-docs/`
-```
+* Skills CLI: `npx skills add smcllns/skills --skill obsidian-html-docs`
+* Manual: [SKILL.md](https://github.com/smcllns/obsidian-plugin-html-docs/blob/main/SKILL.md) (~850 tokens)
 
 ## Test
 
 An E2E test runner validates features, embeds, Canvas cards, and sandboxing are working correctly. Requires `obsidian-cli`, Obsidian running with a vault open, the plugin installed and enabled, and `jq` available.
 
 
 ```bash
-npm test
-npm run release:check
+bun run test
+bun run release:check
 ```
 
-`npm run release:check` runs the production build, the official Obsidian plugin lint rules, and the E2E test. The E2E script builds the current plugin, copies it into the active vault's plugin folder, reloads it, copies `test/fixture.html` into the vault temporarily, opens it in Obsidian, verifies the tab view plus markdown and Canvas embeds, collects the iframe’s own self-test results via `postMessage`, then cleans up.
+`bun run release:check` runs the production build, the official Obsidian plugin lint rules, and the E2E test. The E2E script builds the current plugin, copies it into the active vault's plugin folder, reloads it, copies `test/fixture.html` into the vault temporarily, opens it in Obsidian, verifies the tab view plus markdown and Canvas embeds, collects the iframe’s own self-test results via `postMessage`, then cleans up.
 
 See `test/fixture.html` for the full list of features exercised — and the inline notes for what is intentionally blocked.
 
@@ -79,18 +67,6 @@ Embed HTML docs like other Obsidian embeds. Embeds default to about 600px tall;
 ![[doc.html|600x400]]
 ```
 
-Each iframe receives a one-way snapshot of Obsidian theme styles. HTML docs can use these CSS variables to match light/dark mode, theme colors, and fonts without giving the iframe permission to read Obsidian or the vault. Use fallbacks so files still work outside Obsidian:
-
-```css
-:root {
-  color-scheme: var(--obsidian-color-scheme, light dark);
-  --bg: var(--obsidian-bg, light-dark(#fff, #0e1014));
-  --text: var(--obsidian-text, light-dark(#16161a, #e7e9ec));
-}
-```
-
-Available CSS variables: `--obsidian-color-scheme`, `--obsidian-bg`, `--obsidian-bg-2`, `--obsidian-text`, `--obsidian-text-muted`, `--obsidian-accent`, `--obsidian-border`, `--obsidian-font`, `--obsidian-font-mono`.
-
 ## Obsidian Plugin Docs
 
 * Developer docs: [docs.obsidian.md](https://docs.obsidian.md)

diff --git a/SKILL.md b/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: obsidian-html-docs
+description: Author HTML files for the Obsidian HTML Docs plugin (smcllns/obsidian-plugin-html-docs). Use when creating .html docs intended to render inline in Obsidian: theme tokens, sandbox constraints, asset rules, embed sizing, and things that silently do not work.
+---
+
+# Obsidian HTML Docs authoring guide
+
+The HTML Docs plugin lets users view `.html` files inside Obsidian tabs, markdown embeds, and Canvas cards. It renders each file in a sandboxed iframe via Blob URL. The iframe is sealed (`sandbox="allow-scripts allow-popups allow-forms"`, no `allow-same-origin`) so it cannot reach into Obsidian or the vault. Everything below works within that envelope.
+
+## Default to Obsidian context unless asked otherwise
+
+Before creating the Blob URL, the plugin appends a `<style data-html-docs-theme>` block to your HTML containing a snapshot of the user's current Obsidian design tokens. The iframe does not reach out for these values. They are written as static CSS into your document at load time, then the sandboxed iframe loads that document. **Security boundary unchanged**: no `allow-same-origin`, no reads from the iframe back into Obsidian.
+
+If the user just wants a styled doc that "fits" their vault, use these as your defaults. If they're asking for a specific aesthetic (brutalist poster, retro terminal, Linear-style, an exact brand palette), design freely — Obsidian context is a *hint*, not a constraint.
+
+Injected as static CSS:
+
+- A `color-scheme: light | dark` declaration matching the user's current Obsidian theme
+- `--obsidian-color-scheme`
+- `--obsidian-bg`
+- `--obsidian-bg-2`
+- `--obsidian-text`
+- `--obsidian-text-muted`
+- `--obsidian-accent`
+- `--obsidian-border`
+- `--obsidian-font`
+- `--obsidian-font-mono`
+
+Use Obsidian tokens if present, fall back if not:
+
+```css
+:root {
+  color-scheme: light dark;
+  --bg:   var(--obsidian-bg,   light-dark(#ffffff, #0e1014));
+  --text: var(--obsidian-text, light-dark(#16161a, #e7e9ec));
+}
+```
+
+Open HTML tabs and embeds re-render when the Obsidian theme changes, so the injected snapshot follows theme switches.
+
+## Assets: vault paths do not cross into the iframe
+
+The iframe has no base URL pointing into the vault. Obsidian themes, snippets, and `attachments/...` images don't reach the iframe.
+
+| Pattern | Works? |
+|---|---|
+| `<img src="attachments/foo.png">` | No — fails silently |
+| `<img src="data:image/png;base64,...">` | Yes — fully self-contained |
+| `<img src="https://example.com/foo.png">` | Yes — CORS permitting |
+| Inline `<svg>...</svg>` | Yes — best for icons / diagrams |
+| `<link rel="stylesheet" href="https://cdn...">` | Yes — HTTPS only |
+
+Rules of thumb:
+
+- Small graphics & icons → inline SVG or `data:` URL
+- Photos / large images → upload to a host (R2, CDN) and reference HTTPS
+- Fonts → system stack, or HTTPS CDN
+- Never reference `attachments/` or any vault path — the iframe can't see them
+
+## What works
+
+- HTML / CSS (grid, `light-dark()`, custom properties, animations, gradients, SVG with CSS animations)
+- JavaScript (ES2020+, fetch with CORS, Promises, DOM events, requestAnimationFrame, Canvas 2D)
+- Forms (`allow-forms` is set; intercept `submit` if you don't want navigation)
+- `window.parent.postMessage(msg, '*')` — works even with opaque origin
+- External HTTPS resources (images, fonts on CDNs, fetch APIs that allow CORS)
+- Anchor links (`#section`) and the History API — Blob URL preserves both
+
+## What's blocked
+
+- `localStorage`, `sessionStorage`, `IndexedDB` — `SecurityError`
+- `document.cookie` — throws or silently no-ops
+- Reading `window.parent.*` — cross-origin (postMessage still works)
+- Service workers, geolocation, clipboard, notifications, most permission-gated APIs
+- Top-level navigation from inside the iframe (no `allow-top-navigation`)
+- Vault-relative URLs (see Assets above)
+
+## Linking from markdown to HTML
+
+Wikilinks to `.html` files need the explicit extension:
+
+```markdown
+See: [[my-doc.html]]
+```
+
+`[[my-doc]]` won't resolve to `.html` in stock Obsidian.
+
+## Embed sizing
+
+```markdown
+![[doc.html|600x400]]
+```
+
+Sets the embed width and height. Default markdown embed height is about 600px; tab views fill the pane.
+
+## Pitfalls (skip the turn cost)
+
+- **Theme scripts that read `window.parent`** — always throw under this plugin's sandbox. Don't write them.
+- **Images via `attachments/foo.png`** — won't resolve. Inline as data URL or use HTTPS.
+- **`localStorage` / cookies for state** — blocked. Use URL hash or postMessage to parent.
+- **Hard-coding a palette when Obsidian tokens are available** — defeats the contextual fit. Use `var(--obsidian-*)` with `light-dark()` fallbacks.
+- **Assuming `prefers-color-scheme` == Obsidian theme** — use `--obsidian-color-scheme` or injected colors instead.
diff --git a/docs/handoffs/authoring-skill-release.md b/docs/handoffs/authoring-skill-release.md
@@ -6,12 +6,13 @@ Goal:
 - Be honest that Obsidian plugin installs do not activate agent skills.
 
 Implemented shape:
-- `.agents/SKILL.md` is the canonical source copy in this plugin repo.
-- `esbuild.config.mjs` copies `.agents/SKILL.md` to `dist/html-docs/SKILL.md`.
+- Root `SKILL.md` is the canonical source copy in this plugin repo.
+- `.agents/SKILL.md` mirrors root `SKILL.md` for local agent discovery.
+- `esbuild.config.mjs` copies root `SKILL.md` to `dist/html-docs/SKILL.md`.
 - The release workflow uploads and attests `dist/html-docs/SKILL.md` alongside runtime files.
-- README has an optional agent-skill note explaining discovery roots and the `smcllns/skills` mirror.
+- README has a short optional agent-skill note with the `skills.sh` command and root `SKILL.md` reference.
 - `smcllns/skills` mirrors the canonical skill at `skills/obsidian-html-docs/SKILL.md`.
-- `smcllns/skills` PR #1 was merged first so README can point to the real `skills.sh` install URL.
+- `smcllns/skills` PR #1 was merged first so README can point to the real `skills.sh` install command.
 
 Important constraint:
 - Plugin runtime must not write to agent install roots, dotfiles, or any other user-level configuration. Agent skill activation belongs to the user's agent tooling, not the Obsidian plugin.
@@ -21,11 +22,11 @@ Verification target:
 - `bun run build`
 - `bun run lint`
 - `bun run test`
-- Confirm `dist/html-docs/SKILL.md` matches `.agents/SKILL.md`.
+- Confirm root `SKILL.md`, `.agents/SKILL.md`, and `dist/html-docs/SKILL.md` match.
 
 Current verification:
 - `bun run build` passed.
 - `bun run lint` passed.
 - `bun run test` passed against live Obsidian.
-- `.agents/SKILL.md`, generated `dist/html-docs/SKILL.md`, and the `smcllns/skills` mirror match.
+- Root `SKILL.md`, `.agents/SKILL.md`, generated `dist/html-docs/SKILL.md`, and the `smcllns/skills` mirror match.
 - Haiku critical review found one stale `light-dark()` wording mismatch; fixed by keeping `light-dark()` in the supported CSS list.
diff --git a/esbuild.config.mjs b/esbuild.config.mjs
@@ -16,7 +16,7 @@ const distDir = path.join("dist", "html-docs");
 fs.mkdirSync(distDir, { recursive: true });
 fs.copyFileSync("manifest.json", path.join(distDir, "manifest.json"));
 fs.copyFileSync("styles.css", path.join(distDir, "styles.css"));
-fs.copyFileSync(path.join(".agents", "SKILL.md"), path.join(distDir, "SKILL.md"));
+fs.copyFileSync("SKILL.md", path.join(distDir, "SKILL.md"));
 
 const context = await esbuild.context({
 	banner: { js: banner },

diff --git a/package.json b/package.json
@@ -7,7 +7,7 @@
 		"dev": "node esbuild.config.mjs",
 		"build": "tsc -noEmit -skipLibCheck && node esbuild.config.mjs production",
 		"lint": "eslint .",
-		"release:check": "npm run build && npm run lint && npm test",
+		"release:check": "bun run build && bun run lint && bun run test",
 		"test": "bash test/test.sh"
 	},
 	"keywords": [