stikfix 1.7.0 → 1.7.1

package/README.md

@@ -28,7 +28,7 @@ No cloud. No accounts. No sign-up. Everything stays on `127.0.0.1` — **your co
 ## How it feels to use
 
 1. Click **Enter Review Mode** on any page.
-2. Drop a **sticky note** — free-floating, or click an element to anchor it. Anchored notes auto-capture the CSS selector, computed styles, `outerHTML`, the bounding box, an auto-highlighted screenshot, and the React component name. No describing required.
+2. Drop a **sticky note** — free-floating, or click an element to anchor it. Anchored notes auto-capture the CSS selector, computed styles, `outerHTML`, the bounding box, an auto-highlighted screenshot, and the React component name. No describing required. Want to point at something exactly? **Draw an arrow, box, or circle right on a screenshot** and it rides along with the note.
 3. Tell your agent **"read my notes."** It reads the fresh `.md` files, makes the fixes, and **writes a reply back into each note** — so the pin turns **green ✓** right on the page with a one-line "here's what I changed" (no fix is lost in a chat log). Anything ambiguous turns **amber** with the agent's clarifying question.
 4. Glance at the pins (or open the **notes panel** to filter/search/jump), drop a few more, repeat. Pins update live as the agent works — no refresh. Your UI gets tighter every loop.
 
@@ -36,7 +36,7 @@ No cloud. No accounts. No sign-up. Everything stays on `127.0.0.1` — **your co
 
 ### Windows: one-click installer (recommended)
 
-1. Download **`stikfix-setup-1.6.0.exe`** from the [latest release](https://github.com/omernesh/stikfix/releases/latest).
+1. Download the latest **`stikfix-setup-<version>.exe`** from the [latest release](https://github.com/omernesh/stikfix/releases/latest).
 2. Run it. It needs **administrator rights** — it writes a browser policy so the extension can install itself.
 3. Pick a setup type:
    - **Complete** — installs the host, force-installs the extension into every Chromium browser it finds (Chrome/Edge/Brave), sets the host to run on Windows login, and adds a desktop shortcut. Fully automatic — no terminal.
@@ -49,6 +49,17 @@ The installer ships **`stikfix-host.exe`**, a self-contained binary — no Node.
 
 For advanced use or troubleshooting, the same binary takes subcommands directly: `stikfix-host.exe serve --root <dir>`, `stikfix-host.exe doctor` (prints the health checklist), `stikfix-host.exe register` / `stikfix-host.exe uninstall`.
 
+#### Staying up to date
+
+stikfix keeps itself current with **no reinstalling by hand**:
+
+- **Extension** — auto-updates silently. The installer registers a self-hosted update manifest via enterprise policy, so Chrome/Edge/Brave pull new versions on their own, exactly like a Web Store extension.
+- **Host** — checks GitHub for a newer release on startup and every ~6 hours. When one is available, the **system-tray icon** shows an *update available* balloon and an **Update Stikfix (vX.Y.Z)** item in its right-click menu. Click it and stikfix downloads the new installer, **verifies its SHA-256**, and runs it (one Windows permission prompt) to replace and restart the host — your notes folder and settings are preserved.
+
+The **system-tray icon** is also your at-a-glance host status: green when the host is running, and its menu lets you open the notes folder, stop the host, or apply a pending update.
+
+> Already on an older build? Install the latest `stikfix-setup-<version>.exe` once; from then on, every future version offers itself from the tray with a single click.
+
 ### Developer path (macOS, Linux, or from source on Windows)
 
 Everything the Windows installer automates above, you can also do by hand — this is the path for macOS/Linux, or for building and loading the extension from source.
@@ -95,12 +106,14 @@ Open your app, click **Enter Review Mode**, and start dropping notes. The first
 - **Free notes** — a draggable post-it you can drop anywhere on the page. Captures URL, title, timestamp, viewport, and a screenshot.
 - **Element notes** — click any element and the note auto-captures a robust unique CSS selector ([`@medv/finder`](https://github.com/antonmedv/finder)), curated computed styles, truncated `outerHTML`, bounding box, `data-*`, accessibility role/label, the best-effort **React component name**, and an **auto element-highlight screenshot** showing exactly which element you meant.
 - **Region / marquee capture** — the camera tool dims the page, gives you a crosshair, and lets you drag a rectangle. stikfix hides its own UI, captures, and crops the screenshot DPR-correctly. Stack multiple per note; each is a deletable thumbnail.
+- **Annotation drawing** — mark up exactly what you mean instead of describing it. The pencil tool freezes the current view as a screenshot and drops you into a drawing canvas with **arrow, line, rectangle, circle, and freehand pen** tools, a color palette, and S/M/L thickness. Your drawing is flattened onto the screenshot and attached to the note, so your agent sees the annotated image — pixel-for-pixel.
 - **Persistent on-page pins** — notes stay visible as pins on the page across reloads. View, edit, and delete them in place — backed by host-side CRUD over the localhost relay. Overlapping pins fan out automatically so dense pages stay readable.
 - **Two-way status, on the page** — pins reflect the loop: **unread** (yellow), **flagged** (amber — the agent needs you to clarify, with its question on hover), **resolved** (green ✓ — fixed, with the agent's reply on hover). Resolved notes stay visible so you can verify the fix; archived (`read`) notes disappear.
 - **Notes panel** — a chip-toggled list of every note: counts by status, filter chips, text search, and click-to-jump that scrolls right to the pin. Flip **All pages** to browse every note across the project, not just the current page.
 - **Live updates** — while Review Mode is on, pins and the panel refresh on their own (~4s, only when the tab is visible) as the agent writes replies and resolves notes. No manual reload.
 - **Per-origin project routing** — the first note on a new site opens an OS folder picker; after that, every tab routes to the right project's `notes/` folder automatically. No per-note picking.
 - **Cross-browser host** — one `npx stikfix init` registers Chrome and Edge in a single pass. On Windows, the one-click installer does this (and the browser-side install) for you.
+- **Self-updating** — the browser extension auto-updates via enterprise policy; the Windows host checks GitHub and offers a **SHA-256-verified, one-click update** from its system-tray icon (which also shows live running/stopped status). See [Staying up to date](#staying-up-to-date).
 - **The `review-notes` AI skill** — the portable agent half of the loop (see below).
 
 ## How notes reach your AI
@@ -109,14 +122,18 @@ Every note becomes a markdown file in your project's `notes/` folder, named `<se
 
 The **review-notes** skill is the agent half of the loop. It works through your unread notes in serial order, applies each fix, then writes a short **`reply`** into the note and marks it **`resolved`** (the pin turns green ✓ on the page). Re-running is always idempotent — resolved, flagged, and archived notes are skipped.
 
-**Claude Code (project-local):**
+**Claude Code:** installation is now **automatic** — both the Windows installer's "Install the review-notes skill for Claude Code" task and `npx stikfix init` drop the skill into the user-level `~/.claude/skills/review-notes/SKILL.md`, so it's available in *every* Claude Code project with no manual copy. Pass `npx stikfix init --no-skill` to skip it; `npx stikfix uninstall` removes it.
 
-```bash
-mkdir -p .claude/skills/review-notes
-cp /path/to/stikfix/skill/SKILL.md .claude/skills/review-notes/SKILL.md
-```
+Fallbacks (both optional):
+
+- **Project-local install** — to pin the skill to one repo instead of user-wide:
+
+  ```bash
+  mkdir -p .claude/skills/review-notes
+  cp /path/to/stikfix/skill/SKILL.md .claude/skills/review-notes/SKILL.md
+  ```
 
-**Any other folder-reading agent (Cursor, Codex, etc.):** point it at [`skill/SKILL.md`](skill/SKILL.md) — it's plain markdown, no Claude-specific bits. For example: *"follow the instructions in skill/SKILL.md."*
+- **Any other folder-reading agent (Cursor, Codex, etc.):** point it at [`skill/SKILL.md`](skill/SKILL.md) — it's plain markdown, no Claude-specific bits. For example: *"follow the instructions in skill/SKILL.md."*
 
 **Just say the word.** Any of these kicks it off:
 

package/dist/host/stikfix-init.cjs

@@ -2,8 +2,8 @@
 "use strict";
 
 // bin/stikfix.ts
-var import_node_fs2 = require("node:fs");
-var import_node_path3 = require("node:path");
+var import_node_fs3 = require("node:fs");
+var import_node_path4 = require("node:path");
 var import_node_os2 = require("node:os");
 var import_node_util = require("node:util");
 
@@ -415,6 +415,35 @@ function teardownHost(opts = {}) {
 var import_node_crypto2 = require("node:crypto");
 var STABLE_EXTENSION_ID = "ccdfmbhdcafhmnnnfjpbhgebfkfgjgca";
 
+// bin/skill-install.ts
+var import_node_fs2 = require("node:fs");
+var import_node_path3 = require("node:path");
+function installReviewNotesSkill(homeDir, skillContent) {
+  const dir = (0, import_node_path3.join)(homeDir, ".claude", "skills", "review-notes");
+  const path = (0, import_node_path3.join)(dir, "SKILL.md");
+  try {
+    (0, import_node_fs2.mkdirSync)(dir, { recursive: true });
+    (0, import_node_fs2.writeFileSync)(path, skillContent, { encoding: "utf8" });
+    return { ok: true, path };
+  } catch (err) {
+    return { ok: false, path, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+function removeReviewNotesSkill(homeDir) {
+  const path = (0, import_node_path3.join)(homeDir, ".claude", "skills", "review-notes", "SKILL.md");
+  try {
+    if ((0, import_node_fs2.existsSync)(path)) {
+      (0, import_node_fs2.rmSync)(path, { force: true });
+      return { removed: true, path };
+    }
+  } catch {
+  }
+  return { removed: false, path };
+}
+
+// skill/SKILL.md
+var SKILL_default = '# review-notes\r\n\r\nProcess unread stikfix review notes in serial order \u2014 read each note, apply the\r\nrequested code fix, then update the note\'s status so the extension can surface the\r\nresult on the page. This replaces the screenshot-paste-describe ping-pong of UI\r\nreview with a durable, file-based, iterative loop: a developer drops notes on a live\r\npage, saves them to disk via the stikfix host, then tells you to "read my notes" \u2014\r\nyou fix the code and write a structured reply back into the note, idempotently,\r\nwithout any manual copy-paste.\r\n\r\n## When to use\r\n\r\n- The user says "read my notes", "process review notes", "fix sticky notes", "run\r\n  review-notes", or "what notes do I have"\r\n- There is a `notes/` directory in the project (or an explicit path was given) that\r\n  may contain unread `.md` note files written by the stikfix extension\r\n\r\n## When NOT to use\r\n\r\n- The user wants to view notes without acting on them (read-only inspection)\r\n- The user has not set up the stikfix host and extension (no `notes/` directory)\r\n- You are operating outside the project repository where notes live\r\n\r\n## Preconditions\r\n\r\n- Notes directory: `./notes` relative to the project root, unless the user supplies an\r\n  explicit path argument (e.g. "read my notes in /path/to/project/notes")\r\n- You must be able to read, write, and rename files inside that directory\r\n- The `yaml` library (`yaml@2.9.0`) is available in the project if you need to\r\n  programmatically parse or reserialize frontmatter; alternatively, parse the YAML\r\n  block manually as described in the steps below\r\n\r\n## Git-sync mode (optional)\r\n\r\nstikfix has an opt-in **git-sync mode**: the owner can enable a "Sync notes to\r\ngit" toggle (per project, off by default) that makes the host automatically\r\n`git add`/`git commit`/`git push` each captured note (pathspec-limited to\r\n`notes/`, so it never touches the owner\'s code changes). This lets notes\r\ncaptured on one computer show up \u2014 via `git pull` \u2014 on another computer where\r\nyou run this skill.\r\n\r\n- **Before Step 1 (discovering unread notes):** if the project is a git\r\n  repository, run `git pull` (or `git pull --rebase`) so you see any notes\r\n  pushed from other machines before you list `notes/`. If the pull fails, or\r\n  the project is not a git repo, just continue with whatever notes are on\r\n  disk locally \u2014 never block the run on this.\r\n- **After you resolve or flag a note:** the host only auto-commits *new* note\r\n  captures \u2014 your own edits to a note\'s frontmatter (setting\r\n  `status: resolved`, adding `reply:`, etc.) are plain disk writes the host\r\n  does not know about and will not commit or push. So, only when the project\r\n  is a git repo AND git-sync is in use, after writing your frontmatter\r\n  update(s) also stage, commit, and push just the notes directory:\r\n\r\n  ```\r\n  git add -- notes/ && git commit -m "stikfix: resolve NNNN" && git push\r\n  ```\r\n\r\n  Treat this as best-effort: if the push fails (no network, no remote,\r\n  auth issue), leave the change committed locally and mention it in your\r\n  summary rather than retrying repeatedly. In pure local mode (no git-sync)\r\n  do nothing git-related \u2014 the file writes described in the rest of this\r\n  document are already the whole job.\r\n\r\n## Note frontmatter schema\r\n\r\nEvery note file starts with a YAML frontmatter block. The fields written by the\r\nextension at creation time are:\r\n\r\n```\r\n---\r\nid: 1\r\ncreated: "2026-01-01T12:00:00.000Z"\r\nmode: element          # or: free\r\nurl: "https://example.com/page"\r\ntitle: "Page Title"\r\nviewport:\r\n  width: 1280\r\n  height: 800\r\n  dpr: 1\r\nselector: "#submit-btn"         # element mode only\r\nreact_component: "SubmitButton" # element mode, optional\r\nrect:\r\n  x: 100\r\n  y: 200\r\n  width: 80\r\n  height: 30\r\nscreenshots:\r\n  - "0001-20260101-120000+1.png"\r\nstatus: unread\r\n---\r\n```\r\n\r\nFree-mode notes omit `selector`, `react_component`, and `rect`, and instead include\r\n`note_position: {x, y}`.\r\n\r\nThe AI review loop may add or update the following fields. **Preserve every existing\r\nfield; only add or update `status`, `reply`, and `fixed_in`.**\r\n\r\n| Field | Type | Who sets it | Meaning |\r\n|-------|------|-------------|---------|\r\n| `status` | string | AI | Lifecycle state \u2014 one of `unread`, `flagged`, `resolved`, `read` (see below) |\r\n| `reply` | string | AI | One-line message shown to the developer in the extension UI on hover |\r\n| `fixed_in` | string | AI | Optional commit hash or PR ref where the fix landed (set when `status: resolved`) |\r\n\r\n### Status values and their meaning\r\n\r\n| `status` | Set by | Visual in extension | File renamed? | Meaning |\r\n|----------|--------|---------------------|---------------|---------|\r\n| `unread` | Extension (at creation) | Default pin colour | No | Not yet processed |\r\n| `flagged` | AI | Amber pin; `reply` text on hover | No | Ambiguous \u2014 needs developer clarification |\r\n| `resolved` | AI | Green pin with \u2713; `reply` text on hover | No | AI fixed the issue; developer should verify on page |\r\n| `read` | AI (archive step) | Hidden \u2014 no pin shown | Yes \u2192 `*.read.md` | Archived / dismissed; developer has acknowledged |\r\n\r\n## Steps\r\n\r\n1. **Discover unread notes**\r\n\r\n   List all files in the notes directory. Keep only filenames that end in `.md` AND\r\n   do NOT end in `.read.md` \u2014 both patterns end with `.md`, so the exclusion must be\r\n   explicit. In pseudocode:\r\n\r\n   ```\r\n   unread = files.filter(f => f.endsWith(\'.md\') && !f.endsWith(\'.read.md\'))\r\n   unread.sort()   // ascending lexicographic\r\n   ```\r\n\r\n   The filename format is `<serial>-<YYYYMMDD-HHmmss>.md` where `<serial>` is a\r\n   4-digit zero-padded integer (e.g. `0001`, `0042`). Because every serial is\r\n   zero-padded to exactly 4 digits, ascending lexicographic sort equals serial order\r\n   \u2014 process notes from lowest serial to highest.\r\n\r\n   If there are no unread notes, report "no unread notes" and stop. Do not process\r\n   `*.read.md` files \u2014 they are already done.\r\n\r\n2. **Process each note in serial order**\r\n\r\n   For each unread note filename (lowest serial first):\r\n\r\n   a. **Read the file and parse frontmatter**\r\n\r\n      First, short-circuit on already-handled notes. After parsing the frontmatter,\r\n      check the `status` field BEFORE doing any work:\r\n\r\n      - `status: read` \u2192 skip this note (it is archived; normally it is also renamed\r\n        to `*.read.md` and excluded in Step 1, but skip defensively if you encounter\r\n        it).\r\n      - `status: flagged` \u2192 skip this note. A flagged note was already judged\r\n        ambiguous on a prior run and is awaiting human clarification. Do NOT\r\n        re-process it and do NOT append another `> flagged:` blockquote \u2014 re-flagging\r\n        duplicates the reason line on every run. A flagged note is intentionally NOT\r\n        renamed (it stays a `.md` file so it remains visible), so it WILL reappear in\r\n        the Step 1 listing; the `status: flagged` check here is what makes the re-run\r\n        idempotent for it.\r\n      - `status: resolved` \u2192 skip this note. The fix has been applied on a prior run;\r\n        the note is visible in the extension so the developer can verify it on the\r\n        page. Do NOT re-process or re-rename it.\r\n\r\n      Only continue to the remaining sub-steps (b\u2013e) when `status` is `unread`. This\r\n      mirrors the `classifyNote` helper (`lib/review-notes.ts`), which returns\r\n      `\'read\'`, `\'flagged\'`, or `\'resolved\'` as skip outcomes and only\r\n      `\'fixable\'`/`\'text-only\'` as actionable.\r\n\r\n      Parse the frontmatter by extracting the text between the first `---` pair and\r\n      passing it to a YAML parser.\r\n\r\n      Derive the note\'s serial from `filename.slice(0, 4)` \u2014 NEVER from the `id`\r\n      frontmatter field. The `id` field is stored as an integer and loses its leading\r\n      zeros (the integer `1` is not the string `"0001"`). The filename prefix always\r\n      carries the authoritative zero-padded serial.\r\n\r\n      The text after the closing `---\\n` is the note body. The first non-blank line\r\n      of the body is the developer\'s instruction \u2014 the comment they typed into the\r\n      stikfix note UI. Read it as the actionable request.\r\n\r\n   b. **Read element context (element mode only)**\r\n\r\n      If `mode` is `element`, the body contains a `## Element context` section\r\n      immediately after the developer comment. Use this section to locate the\r\n      relevant code. It looks like:\r\n\r\n      ```markdown\r\n      ## Element context\r\n\r\n      - **Selector:** `#submit-btn`\r\n      - **React component:** `SubmitButton`\r\n      - **Tag / role:** `button` / `button`\r\n      - **Text:** Submit\r\n      - **Rect:** x=100 y=200 w=80 h=30\r\n\r\n      ### Computed styles (curated)\r\n      | prop | value |\r\n      |------|-------|\r\n      | display | inline-flex |\r\n      | color | rgb(255,255,255) |\r\n\r\n      ### outerHTML (truncated)\r\n      ```html\r\n      <button id="submit-btn" class="btn-primary">Submit</button>\r\n      ```\r\n      ```\r\n\r\n      The selector, React component name, tag, text, computed styles, and outerHTML\r\n      together give you enough context to locate the exact element in the codebase\r\n      without guessing. Use `grep`, a file search, or your knowledge of the project\r\n      structure to find the relevant source file(s).\r\n\r\n   c. **Open screenshots (if available and present on disk)**\r\n\r\n      The frontmatter `screenshots` field is an array of filenames. These filenames\r\n      are relative to the **notes directory**, not the project root. Resolve each\r\n      screenshot path by joining it with the notes directory path:\r\n\r\n      ```\r\n      screenshotAbsPath = join(notesDir, screenshotFilename)\r\n      ```\r\n\r\n      If `screenshots` is non-empty AND the referenced PNG files exist on disk, open\r\n      them with vision when the text description or element context alone is\r\n      insufficient to understand the issue.\r\n\r\n      If a referenced screenshot file does not exist on disk, emit exactly one line:\r\n\r\n      ```\r\n      WARN: <filename> not found \u2014 proceeding text-only\r\n      ```\r\n\r\n      Then continue processing the note as a text-only note. A missing screenshot is\r\n      NOT ambiguous \u2014 the developer instruction and element context remain actionable.\r\n      Do not flag the note or skip it because of a missing screenshot.\r\n\r\n   d. **Apply the fix**\r\n\r\n      Using all available context \u2014 the developer instruction, element context\r\n      (selector, computed styles, outerHTML), and any screenshots \u2014 apply the\r\n      requested fix to the relevant source file(s) in the project.\r\n\r\n      If the instruction is genuinely ambiguous even after reading the element\r\n      context and any screenshots \u2014 for example, "make this better" with no\r\n      actionable target and no element context \u2014 do NOT attempt a fix. Instead:\r\n\r\n      - Update the frontmatter: set `status` from `unread` to `flagged`, and add a\r\n        `reply:` field containing a short, one-line clarification question directed at\r\n        the developer (e.g. `reply: "Which colour should the button be \u2014 brand blue or\r\n        red?"`)\r\n      - Optionally also append a blockquote line to the end of the note body for\r\n        human readability:\r\n        ```\r\n        > flagged: <brief reason why the instruction is ambiguous>\r\n        ```\r\n        (The canonical machine-readable signal is the `reply:` frontmatter field; the\r\n        blockquote is supplementary.)\r\n      - Leave the filename unchanged (do NOT rename to `.read.md` or any other name)\r\n      - Skip to the next note\r\n\r\n      The extension renders flagged pins in amber and shows the `reply` text on hover,\r\n      so the developer sees exactly what question to answer.\r\n\r\n      For all other cases (clear instruction, missing-screenshot text-only, element\r\n      mode with context), proceed with the fix and continue to step (e).\r\n\r\n   e. **Mark the note as resolved \u2014 ONLY after a successful fix**\r\n\r\n      The frontmatter update is the LAST action, performed only after the fix has been\r\n      successfully applied. This ordering is the core reliability guarantee: if the fix\r\n      fails or is interrupted, the note stays `unread` and will be retried on the next\r\n      run.\r\n\r\n      **Update the frontmatter:** Parse the YAML block, set `status: resolved`, add a\r\n      `reply:` field with a one-line description of what was done, and optionally add\r\n      `fixed_in:` with the commit hash or PR ref. Preserve every other existing field.\r\n\r\n      ```\r\n      rawFm = content between the first --- pair\r\n      fm = yaml.parse(rawFm)\r\n      fm[\'status\'] = \'resolved\'\r\n      fm[\'reply\'] = \'Renamed Submit \u2192 Save Changes in Header.tsx\'   // what you did\r\n      fm[\'fixed_in\'] = \'abc1234\'   // optional: commit hash or PR ref\r\n      newFmBlock = \'---\\n\' + yaml.stringify(fm) + \'---\\n\'\r\n      newContent = newFmBlock + bodyAfterFrontmatter\r\n      writeFile(mdPath, newContent)\r\n      ```\r\n\r\n      The project\'s `yaml` library (`yaml@2.9.0`, import `{ parse, stringify } from\r\n      \'yaml\'`) handles colons and quotes in URL values correctly \u2014 do not hand-roll\r\n      YAML serialization.\r\n\r\n      **Do NOT rename the file.** A resolved note stays as `<serial>-<timestamp>.md`\r\n      so it remains visible in the extension as a green pin with a \u2713. The developer\r\n      must be able to see the fix confirmation on the page before dismissing the note.\r\n\r\n      **Archive / dismiss (separate, later step):** Only when the developer has\r\n      acknowledged a resolved note (or explicitly wants to dismiss a note) should the\r\n      note be archived. Archiving means:\r\n\r\n      - Set `status: read` in the frontmatter\r\n      - Rename the file: `readPath = mdPath.replace(/\\.md$/, \'.read.md\')`\r\n\r\n      This two-step approach (status:read + rename to *.read.md) is belt-and-suspenders:\r\n      the rename is the primary skip signal on the next run (excluded by the glob in\r\n      Step 1); the `status: read` frontmatter field lets other tools (like\r\n      `listAnnotations` in the host) still list the note while knowing it is archived.\r\n      The archive step is NOT done automatically after fixing \u2014 it is a separate,\r\n      developer-triggered action.\r\n\r\n3. **Report a terse summary**\r\n\r\n   After processing all notes, report:\r\n\r\n   ```\r\n   Processed N notes: M resolved (fix applied), K flagged (needs clarification), J skipped (resolved/read).\r\n   ```\r\n\r\n   If any notes were resolved, list their filenames and the `reply` text (what was\r\n   done) so the developer knows what to verify on the page.\r\n\r\n   If any notes were flagged, list their filenames and the `reply` question so the\r\n   developer knows what to clarify.\r\n\r\n## After the pass\r\n\r\nOn the next run:\r\n\r\n- `resolved` notes: still present as `.md` files (not renamed), skipped by the\r\n  `status: resolved` check in Step 2a. They remain visible on the page as green pins\r\n  until the developer archives them.\r\n- `flagged` notes: skipped by the `status: flagged` check in Step 2a. They remain\r\n  visible on the page as amber pins until the developer answers the question and the\r\n  note is re-opened for processing.\r\n- `read` notes: excluded by the Step 1 glob (renamed to `*.read.md`) and skipped\r\n  defensively by the `status: read` check if encountered anyway.\r\n\r\nA re-run on a fully-processed directory does no fixing work and reports either "no\r\nunread notes" (all `unread` notes have been resolved or flagged) or that only\r\npreviously-flagged notes remain. This is the idempotency guarantee \u2014 re-running never\r\nre-applies a fix, never re-resolves an already-resolved note, and never appends a\r\nduplicate `> flagged:` blockquote.\r\n\r\n## Forbidden patterns (do not do these)\r\n\r\n- **Glob `*.md` without excluding `*.read.md`** \u2014 `.read.md` files end in `.md`; a\r\n  naive glob will reprocess already-archived notes\r\n- **Derive serial from the `id` frontmatter field** \u2014 the integer `id` loses zero-\r\n  padding; always use `filename.slice(0, 4)`\r\n- **Set `status: read` on a successful fix** \u2014 a successful fix must set\r\n  `status: resolved` (not `read`). `read` is the archive state, set only after the\r\n  developer has acknowledged the resolved note. Getting this wrong hides the green pin\r\n  before the developer can verify the fix.\r\n- **Rename the file after a fix** \u2014 resolved notes are NOT renamed. Renaming to\r\n  `*.read.md` is the archive step, not the fix-completion step.\r\n- **Rename before fix** \u2014 for the archive step (if triggered), write the updated\r\n  status first; rename is always the last action\r\n- **Treat a missing screenshot as ambiguous** \u2014 warn once and proceed text-only;\r\n  only an unclear developer instruction triggers the flagged path\r\n- **Overwrite existing frontmatter fields** \u2014 always parse the YAML block, update\r\n  only `status`, `reply`, and `fixed_in`, and reserialize. Never clobber `id`,\r\n  `created`, `url`, `selector`, or any other field the extension wrote.\r\n- **Make network or host calls to the stikfix host** \u2014 this skill is disk-only with\r\n  respect to stikfix itself; do not call the stikfix host HTTP API, do not POST to\r\n  any endpoint. (The local `git` CLI \u2014 `pull`/`add`/`commit`/`push` \u2014 is explicitly\r\n  permitted, and expected in git-sync mode; see "Git-sync mode (optional)" above.\r\n  That is a plain local git operation, not a call to the stikfix host.)\r\n';
+
 // bin/stikfix.ts
 var { values, positionals } = (0, import_node_util.parseArgs)({
   allowPositionals: true,
@@ -424,7 +453,8 @@ var { values, positionals } = (0, import_node_util.parseArgs)({
     port: { type: "string" },
     browser: { type: "string" },
     startup: { type: "boolean" },
-    "no-startup": { type: "boolean" }
+    "no-startup": { type: "boolean" },
+    "no-skill": { type: "boolean" }
   },
   strict: false
 });
@@ -467,8 +497,8 @@ function resolveStartupChoice(forceOn, forceOff, isTTY) {
   }
   return false;
 }
-var CONFIG_DIR2 = (0, import_node_path3.join)((0, import_node_os2.homedir)(), ".config", "stikfix");
-var CONFIG_PATH2 = (0, import_node_path3.join)(CONFIG_DIR2, "config.json");
+var CONFIG_DIR2 = (0, import_node_path4.join)((0, import_node_os2.homedir)(), ".config", "stikfix");
+var CONFIG_PATH2 = (0, import_node_path4.join)(CONFIG_DIR2, "config.json");
 if (subcommand === "init") {
   const rawRoot = values["root"];
   const rawExtId = values["extension-id"];
@@ -482,38 +512,38 @@ if (subcommand === "init") {
   const isFirefox = browser === "firefox";
   const extensionId = rawExtId && typeof rawExtId === "string" ? rawExtId : isFirefox ? DEFAULT_GECKO_ID : STABLE_EXTENSION_ID;
   const port = rawPort ? parseInt(rawPort, 10) : void 0;
-  const root = (0, import_node_path3.resolve)(rootArg);
-  const name = (0, import_node_path3.basename)(root);
-  const notesDir = (0, import_node_path3.join)(root, "notes");
-  const hostEntryPath = (0, import_node_path3.resolve)((0, import_node_path3.join)(__dirname, "src", "index.js"));
-  (0, import_node_fs2.mkdirSync)(CONFIG_DIR2, { recursive: true });
+  const root = (0, import_node_path4.resolve)(rootArg);
+  const name = (0, import_node_path4.basename)(root);
+  const notesDir = (0, import_node_path4.join)(root, "notes");
+  const hostEntryPath = (0, import_node_path4.resolve)((0, import_node_path4.join)(__dirname, "src", "index.js"));
+  (0, import_node_fs3.mkdirSync)(CONFIG_DIR2, { recursive: true });
   const config = { root, name, notesDir, hostEntry: hostEntryPath, nodePath: process.execPath };
-  (0, import_node_fs2.writeFileSync)(CONFIG_PATH2, JSON.stringify(config, null, 2), { encoding: "utf8", mode: 384 });
-  const hostBinPath = (0, import_node_path3.resolve)((0, import_node_path3.join)(__dirname, "stikfix-native.cjs"));
+  (0, import_node_fs3.writeFileSync)(CONFIG_PATH2, JSON.stringify(config, null, 2), { encoding: "utf8", mode: 384 });
+  const hostBinPath = (0, import_node_path4.resolve)((0, import_node_path4.join)(__dirname, "stikfix-native.cjs"));
   try {
     registerNativeHost({ extensionId, hostBinPath, browser });
   } catch (err) {
     console.error("stikfix init: failed to register native host:", String(err));
     process.exit(1);
   }
-  const projectRoot = (0, import_node_path3.resolve)((0, import_node_path3.join)(__dirname, "..", ".."));
+  const projectRoot = (0, import_node_path4.resolve)((0, import_node_path4.join)(__dirname, "..", ".."));
   const firefoxOutputCandidates = [
-    (0, import_node_path3.join)(projectRoot, ".output", "firefox-mv2"),
-    (0, import_node_path3.join)(projectRoot, ".output", "firefox-mv3")
+    (0, import_node_path4.join)(projectRoot, ".output", "firefox-mv2"),
+    (0, import_node_path4.join)(projectRoot, ".output", "firefox-mv3")
   ];
-  const chromeOutputDir = (0, import_node_path3.join)(projectRoot, ".output", "chrome-mv3");
-  const browserOutputDir = isFirefox ? firefoxOutputCandidates.find((d) => (0, import_node_fs2.existsSync)(d)) ?? firefoxOutputCandidates[1] : chromeOutputDir;
+  const chromeOutputDir = (0, import_node_path4.join)(projectRoot, ".output", "chrome-mv3");
+  const browserOutputDir = isFirefox ? firefoxOutputCandidates.find((d) => (0, import_node_fs3.existsSync)(d)) ?? firefoxOutputCandidates[1] : chromeOutputDir;
   const icoCandidates = [
-    (0, import_node_path3.join)(projectRoot, "public", "icon", "stikfix.ico"),
-    (0, import_node_path3.join)(browserOutputDir, "icon", "stikfix.ico")
+    (0, import_node_path4.join)(projectRoot, "public", "icon", "stikfix.ico"),
+    (0, import_node_path4.join)(browserOutputDir, "icon", "stikfix.ico")
   ];
   const pngCandidates = [
-    (0, import_node_path3.join)(browserOutputDir, "icon", "128.png"),
-    (0, import_node_path3.join)(projectRoot, "public", "icon", "128.png"),
-    (0, import_node_path3.join)(projectRoot, "assets", "icon", "128.png")
+    (0, import_node_path4.join)(browserOutputDir, "icon", "128.png"),
+    (0, import_node_path4.join)(projectRoot, "public", "icon", "128.png"),
+    (0, import_node_path4.join)(projectRoot, "assets", "icon", "128.png")
   ];
   const iconCandidates = process.platform === "win32" ? [...icoCandidates, ...pngCandidates] : pngCandidates;
-  const iconPath = iconCandidates.find((p) => (0, import_node_fs2.existsSync)(p));
+  const iconPath = iconCandidates.find((p) => (0, import_node_fs3.existsSync)(p));
   const launcherResult = createLauncherFiles({
     hostEntryPath,
     root,
@@ -568,18 +598,18 @@ if (subcommand === "init") {
   if (isFirefox) {
     console.log("  1. Load the extension (temporary add-on):");
     console.log("       about:debugging#/runtime/this-firefox  \u2192  Load Temporary Add-on\u2026");
-    console.log("       Pick: " + (0, import_node_path3.resolve)((0, import_node_path3.join)(browserOutputDir, "manifest.json")));
+    console.log("       Pick: " + (0, import_node_path4.resolve)((0, import_node_path4.join)(browserOutputDir, "manifest.json")));
   } else {
     console.log("  1. Load the extension (unpacked):");
     console.log("       chrome://extensions  \u2192  Developer mode ON  \u2192  Load unpacked");
-    console.log("       Folder: " + (0, import_node_path3.resolve)(browserOutputDir));
+    console.log("       Folder: " + (0, import_node_path4.resolve)(browserOutputDir));
   }
   console.log("");
   console.log("  2. Start the backend \u2014 double-click the desktop launcher:");
   if (process.platform === "win32") {
     const lnkPath = launcherResult.written.find((p) => p.endsWith(".lnk")) ?? "";
     const batchPath = launcherResult.written.find((p) => p.endsWith(".bat")) ?? "";
-    if (lnkPath && (0, import_node_fs2.existsSync)(lnkPath)) {
+    if (lnkPath && (0, import_node_fs3.existsSync)(lnkPath)) {
       console.log('       Desktop shortcut: "Stikfix Host" (icon on your Desktop)');
     } else if (batchPath) {
       console.log("       Batch file: " + batchPath);
@@ -600,6 +630,17 @@ if (subcommand === "init") {
   console.log("");
   console.log("  Extension ID: " + extensionId);
   console.log("");
+  if (values["no-skill"] === true) {
+    console.log("  Skill:        skipped \u2014 review-notes skill not installed (--no-skill).");
+  } else {
+    const skillResult = installReviewNotesSkill((0, import_node_os2.homedir)(), SKILL_default);
+    if (skillResult.ok) {
+      console.log("  \u2713 Installed the review-notes skill for Claude Code \u2192 " + skillResult.path);
+    } else {
+      console.error("stikfix init: could not install review-notes skill: " + skillResult.error + " (copy skill/SKILL.md manually)");
+    }
+  }
+  console.log("");
   console.log("To keep the host up-to-date:");
   console.log("  npx --yes stikfix@latest init --root " + root);
 } else if (subcommand === "uninstall") {
@@ -611,15 +652,21 @@ if (subcommand === "init") {
   if (teardown.startupError) {
     console.error("stikfix uninstall: error removing startup entry:", teardown.startupError);
   }
+  const skillRemoval = removeReviewNotesSkill((0, import_node_os2.homedir)());
   console.log("stikfix: native host unregistered.");
   console.log("  manifest removed");
   console.log("  launcher files removed");
   console.log("  startup entry removed");
   console.log("  config removed");
+  console.log(
+    skillRemoval.removed ? "  review-notes skill removed" : "  review-notes skill not present (nothing to remove)"
+  );
 } else {
-  console.error("Usage: npx stikfix <init|uninstall> [--root <dir>] [--browser <chrome|firefox>] [--extension-id <id>] [--port <port>]");
+  console.error("Usage: npx stikfix <init|uninstall> [--root <dir>] [--browser <chrome|firefox>] [--extension-id <id>] [--port <port>] [--no-skill]");
+  console.error("");
+  console.error("  init        Register the native host, write config, and install the review-notes skill");
+  console.error("  uninstall   Remove the native host manifest, launchers, config, and review-notes skill");
   console.error("");
-  console.error("  init        Register the native host and write config");
-  console.error("  uninstall   Remove the native host manifest, launchers, and config");
+  console.error("  --no-skill  (init) Skip installing the review-notes Claude Code skill");
   process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stikfix",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Pin sticky notes on any page — your AI reads them.",
   "license": "MIT",
   "author": "Omer Nesher <omernesher@gmail.com>",
@@ -36,6 +36,7 @@
     "dist/host/stikfix-init.cjs",
     "dist/host/stikfix-native.cjs",
     "public/icon",
+    "skill/SKILL.md",
     "README.md",
     "LICENSE"
   ],
@@ -44,7 +45,7 @@
   },
   "scripts": {
     "dev": "wxt",
-    "build:host-bin": "npx esbuild bin/stikfix.ts --platform=node --format=cjs --bundle \"--external:node:*\" --outfile=dist/host/stikfix-init.cjs && npx esbuild host/src/native-host.ts --platform=node --format=cjs --bundle \"--external:node:*\" --outfile=dist/host/stikfix-native.cjs",
+    "build:host-bin": "npx esbuild bin/stikfix.ts --platform=node --format=cjs --bundle \"--external:node:*\" \"--loader:.md=text\" --outfile=dist/host/stikfix-init.cjs && npx esbuild host/src/native-host.ts --platform=node --format=cjs --bundle \"--external:node:*\" --outfile=dist/host/stikfix-native.cjs",
     "build": "wxt build && tsc -p tsconfig.host.json && npm run build:host-bin",
     "build:firefox": "wxt build -b firefox && tsc -p tsconfig.host.json && npm run build:host-bin",
     "host": "node dist/host/src/index.js",

package/skill/SKILL.md

@@ -0,0 +1,361 @@
+# review-notes
+
+Process unread stikfix review notes in serial order — read each note, apply the
+requested code fix, then update the note's status so the extension can surface the
+result on the page. This replaces the screenshot-paste-describe ping-pong of UI
+review with a durable, file-based, iterative loop: a developer drops notes on a live
+page, saves them to disk via the stikfix host, then tells you to "read my notes" —
+you fix the code and write a structured reply back into the note, idempotently,
+without any manual copy-paste.
+
+## When to use
+
+- The user says "read my notes", "process review notes", "fix sticky notes", "run
+  review-notes", or "what notes do I have"
+- There is a `notes/` directory in the project (or an explicit path was given) that
+  may contain unread `.md` note files written by the stikfix extension
+
+## When NOT to use
+
+- The user wants to view notes without acting on them (read-only inspection)
+- The user has not set up the stikfix host and extension (no `notes/` directory)
+- You are operating outside the project repository where notes live
+
+## Preconditions
+
+- Notes directory: `./notes` relative to the project root, unless the user supplies an
+  explicit path argument (e.g. "read my notes in /path/to/project/notes")
+- You must be able to read, write, and rename files inside that directory
+- The `yaml` library (`yaml@2.9.0`) is available in the project if you need to
+  programmatically parse or reserialize frontmatter; alternatively, parse the YAML
+  block manually as described in the steps below
+
+## Git-sync mode (optional)
+
+stikfix has an opt-in **git-sync mode**: the owner can enable a "Sync notes to
+git" toggle (per project, off by default) that makes the host automatically
+`git add`/`git commit`/`git push` each captured note (pathspec-limited to
+`notes/`, so it never touches the owner's code changes). This lets notes
+captured on one computer show up — via `git pull` — on another computer where
+you run this skill.
+
+- **Before Step 1 (discovering unread notes):** if the project is a git
+  repository, run `git pull` (or `git pull --rebase`) so you see any notes
+  pushed from other machines before you list `notes/`. If the pull fails, or
+  the project is not a git repo, just continue with whatever notes are on
+  disk locally — never block the run on this.
+- **After you resolve or flag a note:** the host only auto-commits *new* note
+  captures — your own edits to a note's frontmatter (setting
+  `status: resolved`, adding `reply:`, etc.) are plain disk writes the host
+  does not know about and will not commit or push. So, only when the project
+  is a git repo AND git-sync is in use, after writing your frontmatter
+  update(s) also stage, commit, and push just the notes directory:
+
+  ```
+  git add -- notes/ && git commit -m "stikfix: resolve NNNN" && git push
+  ```
+
+  Treat this as best-effort: if the push fails (no network, no remote,
+  auth issue), leave the change committed locally and mention it in your
+  summary rather than retrying repeatedly. In pure local mode (no git-sync)
+  do nothing git-related — the file writes described in the rest of this
+  document are already the whole job.
+
+## Note frontmatter schema
+
+Every note file starts with a YAML frontmatter block. The fields written by the
+extension at creation time are:
+
+```
+---
+id: 1
+created: "2026-01-01T12:00:00.000Z"
+mode: element          # or: free
+url: "https://example.com/page"
+title: "Page Title"
+viewport:
+  width: 1280
+  height: 800
+  dpr: 1
+selector: "#submit-btn"         # element mode only
+react_component: "SubmitButton" # element mode, optional
+rect:
+  x: 100
+  y: 200
+  width: 80
+  height: 30
+screenshots:
+  - "0001-20260101-120000+1.png"
+status: unread
+---
+```
+
+Free-mode notes omit `selector`, `react_component`, and `rect`, and instead include
+`note_position: {x, y}`.
+
+The AI review loop may add or update the following fields. **Preserve every existing
+field; only add or update `status`, `reply`, and `fixed_in`.**
+
+| Field | Type | Who sets it | Meaning |
+|-------|------|-------------|---------|
+| `status` | string | AI | Lifecycle state — one of `unread`, `flagged`, `resolved`, `read` (see below) |
+| `reply` | string | AI | One-line message shown to the developer in the extension UI on hover |
+| `fixed_in` | string | AI | Optional commit hash or PR ref where the fix landed (set when `status: resolved`) |
+
+### Status values and their meaning
+
+| `status` | Set by | Visual in extension | File renamed? | Meaning |
+|----------|--------|---------------------|---------------|---------|
+| `unread` | Extension (at creation) | Default pin colour | No | Not yet processed |
+| `flagged` | AI | Amber pin; `reply` text on hover | No | Ambiguous — needs developer clarification |
+| `resolved` | AI | Green pin with ✓; `reply` text on hover | No | AI fixed the issue; developer should verify on page |
+| `read` | AI (archive step) | Hidden — no pin shown | Yes → `*.read.md` | Archived / dismissed; developer has acknowledged |
+
+## Steps
+
+1. **Discover unread notes**
+
+   List all files in the notes directory. Keep only filenames that end in `.md` AND
+   do NOT end in `.read.md` — both patterns end with `.md`, so the exclusion must be
+   explicit. In pseudocode:
+
+   ```
+   unread = files.filter(f => f.endsWith('.md') && !f.endsWith('.read.md'))
+   unread.sort()   // ascending lexicographic
+   ```
+
+   The filename format is `<serial>-<YYYYMMDD-HHmmss>.md` where `<serial>` is a
+   4-digit zero-padded integer (e.g. `0001`, `0042`). Because every serial is
+   zero-padded to exactly 4 digits, ascending lexicographic sort equals serial order
+   — process notes from lowest serial to highest.
+
+   If there are no unread notes, report "no unread notes" and stop. Do not process
+   `*.read.md` files — they are already done.
+
+2. **Process each note in serial order**
+
+   For each unread note filename (lowest serial first):
+
+   a. **Read the file and parse frontmatter**
+
+      First, short-circuit on already-handled notes. After parsing the frontmatter,
+      check the `status` field BEFORE doing any work:
+
+      - `status: read` → skip this note (it is archived; normally it is also renamed
+        to `*.read.md` and excluded in Step 1, but skip defensively if you encounter
+        it).
+      - `status: flagged` → skip this note. A flagged note was already judged
+        ambiguous on a prior run and is awaiting human clarification. Do NOT
+        re-process it and do NOT append another `> flagged:` blockquote — re-flagging
+        duplicates the reason line on every run. A flagged note is intentionally NOT
+        renamed (it stays a `.md` file so it remains visible), so it WILL reappear in
+        the Step 1 listing; the `status: flagged` check here is what makes the re-run
+        idempotent for it.
+      - `status: resolved` → skip this note. The fix has been applied on a prior run;
+        the note is visible in the extension so the developer can verify it on the
+        page. Do NOT re-process or re-rename it.
+
+      Only continue to the remaining sub-steps (b–e) when `status` is `unread`. This
+      mirrors the `classifyNote` helper (`lib/review-notes.ts`), which returns
+      `'read'`, `'flagged'`, or `'resolved'` as skip outcomes and only
+      `'fixable'`/`'text-only'` as actionable.
+
+      Parse the frontmatter by extracting the text between the first `---` pair and
+      passing it to a YAML parser.
+
+      Derive the note's serial from `filename.slice(0, 4)` — NEVER from the `id`
+      frontmatter field. The `id` field is stored as an integer and loses its leading
+      zeros (the integer `1` is not the string `"0001"`). The filename prefix always
+      carries the authoritative zero-padded serial.
+
+      The text after the closing `---\n` is the note body. The first non-blank line
+      of the body is the developer's instruction — the comment they typed into the
+      stikfix note UI. Read it as the actionable request.
+
+   b. **Read element context (element mode only)**
+
+      If `mode` is `element`, the body contains a `## Element context` section
+      immediately after the developer comment. Use this section to locate the
+      relevant code. It looks like:
+
+      ```markdown
+      ## Element context
+
+      - **Selector:** `#submit-btn`
+      - **React component:** `SubmitButton`
+      - **Tag / role:** `button` / `button`
+      - **Text:** Submit
+      - **Rect:** x=100 y=200 w=80 h=30
+
+      ### Computed styles (curated)
+      | prop | value |
+      |------|-------|
+      | display | inline-flex |
+      | color | rgb(255,255,255) |
+
+      ### outerHTML (truncated)
+      ```html
+      <button id="submit-btn" class="btn-primary">Submit</button>
+      ```
+      ```
+
+      The selector, React component name, tag, text, computed styles, and outerHTML
+      together give you enough context to locate the exact element in the codebase
+      without guessing. Use `grep`, a file search, or your knowledge of the project
+      structure to find the relevant source file(s).
+
+   c. **Open screenshots (if available and present on disk)**
+
+      The frontmatter `screenshots` field is an array of filenames. These filenames
+      are relative to the **notes directory**, not the project root. Resolve each
+      screenshot path by joining it with the notes directory path:
+
+      ```
+      screenshotAbsPath = join(notesDir, screenshotFilename)
+      ```
+
+      If `screenshots` is non-empty AND the referenced PNG files exist on disk, open
+      them with vision when the text description or element context alone is
+      insufficient to understand the issue.
+
+      If a referenced screenshot file does not exist on disk, emit exactly one line:
+
+      ```
+      WARN: <filename> not found — proceeding text-only
+      ```
+
+      Then continue processing the note as a text-only note. A missing screenshot is
+      NOT ambiguous — the developer instruction and element context remain actionable.
+      Do not flag the note or skip it because of a missing screenshot.
+
+   d. **Apply the fix**
+
+      Using all available context — the developer instruction, element context
+      (selector, computed styles, outerHTML), and any screenshots — apply the
+      requested fix to the relevant source file(s) in the project.
+
+      If the instruction is genuinely ambiguous even after reading the element
+      context and any screenshots — for example, "make this better" with no
+      actionable target and no element context — do NOT attempt a fix. Instead:
+
+      - Update the frontmatter: set `status` from `unread` to `flagged`, and add a
+        `reply:` field containing a short, one-line clarification question directed at
+        the developer (e.g. `reply: "Which colour should the button be — brand blue or
+        red?"`)
+      - Optionally also append a blockquote line to the end of the note body for
+        human readability:
+        ```
+        > flagged: <brief reason why the instruction is ambiguous>
+        ```
+        (The canonical machine-readable signal is the `reply:` frontmatter field; the
+        blockquote is supplementary.)
+      - Leave the filename unchanged (do NOT rename to `.read.md` or any other name)
+      - Skip to the next note
+
+      The extension renders flagged pins in amber and shows the `reply` text on hover,
+      so the developer sees exactly what question to answer.
+
+      For all other cases (clear instruction, missing-screenshot text-only, element
+      mode with context), proceed with the fix and continue to step (e).
+
+   e. **Mark the note as resolved — ONLY after a successful fix**
+
+      The frontmatter update is the LAST action, performed only after the fix has been
+      successfully applied. This ordering is the core reliability guarantee: if the fix
+      fails or is interrupted, the note stays `unread` and will be retried on the next
+      run.
+
+      **Update the frontmatter:** Parse the YAML block, set `status: resolved`, add a
+      `reply:` field with a one-line description of what was done, and optionally add
+      `fixed_in:` with the commit hash or PR ref. Preserve every other existing field.
+
+      ```
+      rawFm = content between the first --- pair
+      fm = yaml.parse(rawFm)
+      fm['status'] = 'resolved'
+      fm['reply'] = 'Renamed Submit → Save Changes in Header.tsx'   // what you did
+      fm['fixed_in'] = 'abc1234'   // optional: commit hash or PR ref
+      newFmBlock = '---\n' + yaml.stringify(fm) + '---\n'
+      newContent = newFmBlock + bodyAfterFrontmatter
+      writeFile(mdPath, newContent)
+      ```
+
+      The project's `yaml` library (`yaml@2.9.0`, import `{ parse, stringify } from
+      'yaml'`) handles colons and quotes in URL values correctly — do not hand-roll
+      YAML serialization.
+
+      **Do NOT rename the file.** A resolved note stays as `<serial>-<timestamp>.md`
+      so it remains visible in the extension as a green pin with a ✓. The developer
+      must be able to see the fix confirmation on the page before dismissing the note.
+
+      **Archive / dismiss (separate, later step):** Only when the developer has
+      acknowledged a resolved note (or explicitly wants to dismiss a note) should the
+      note be archived. Archiving means:
+
+      - Set `status: read` in the frontmatter
+      - Rename the file: `readPath = mdPath.replace(/\.md$/, '.read.md')`
+
+      This two-step approach (status:read + rename to *.read.md) is belt-and-suspenders:
+      the rename is the primary skip signal on the next run (excluded by the glob in
+      Step 1); the `status: read` frontmatter field lets other tools (like
+      `listAnnotations` in the host) still list the note while knowing it is archived.
+      The archive step is NOT done automatically after fixing — it is a separate,
+      developer-triggered action.
+
+3. **Report a terse summary**
+
+   After processing all notes, report:
+
+   ```
+   Processed N notes: M resolved (fix applied), K flagged (needs clarification), J skipped (resolved/read).
+   ```
+
+   If any notes were resolved, list their filenames and the `reply` text (what was
+   done) so the developer knows what to verify on the page.
+
+   If any notes were flagged, list their filenames and the `reply` question so the
+   developer knows what to clarify.
+
+## After the pass
+
+On the next run:
+
+- `resolved` notes: still present as `.md` files (not renamed), skipped by the
+  `status: resolved` check in Step 2a. They remain visible on the page as green pins
+  until the developer archives them.
+- `flagged` notes: skipped by the `status: flagged` check in Step 2a. They remain
+  visible on the page as amber pins until the developer answers the question and the
+  note is re-opened for processing.
+- `read` notes: excluded by the Step 1 glob (renamed to `*.read.md`) and skipped
+  defensively by the `status: read` check if encountered anyway.
+
+A re-run on a fully-processed directory does no fixing work and reports either "no
+unread notes" (all `unread` notes have been resolved or flagged) or that only
+previously-flagged notes remain. This is the idempotency guarantee — re-running never
+re-applies a fix, never re-resolves an already-resolved note, and never appends a
+duplicate `> flagged:` blockquote.
+
+## Forbidden patterns (do not do these)
+
+- **Glob `*.md` without excluding `*.read.md`** — `.read.md` files end in `.md`; a
+  naive glob will reprocess already-archived notes
+- **Derive serial from the `id` frontmatter field** — the integer `id` loses zero-
+  padding; always use `filename.slice(0, 4)`
+- **Set `status: read` on a successful fix** — a successful fix must set
+  `status: resolved` (not `read`). `read` is the archive state, set only after the
+  developer has acknowledged the resolved note. Getting this wrong hides the green pin
+  before the developer can verify the fix.
+- **Rename the file after a fix** — resolved notes are NOT renamed. Renaming to
+  `*.read.md` is the archive step, not the fix-completion step.
+- **Rename before fix** — for the archive step (if triggered), write the updated
+  status first; rename is always the last action
+- **Treat a missing screenshot as ambiguous** — warn once and proceed text-only;
+  only an unclear developer instruction triggers the flagged path
+- **Overwrite existing frontmatter fields** — always parse the YAML block, update
+  only `status`, `reply`, and `fixed_in`, and reserialize. Never clobber `id`,
+  `created`, `url`, `selector`, or any other field the extension wrote.
+- **Make network or host calls to the stikfix host** — this skill is disk-only with
+  respect to stikfix itself; do not call the stikfix host HTTP API, do not POST to
+  any endpoint. (The local `git` CLI — `pull`/`add`/`commit`/`push` — is explicitly
+  permitted, and expected in git-sync mode; see "Git-sync mode (optional)" above.
+  That is a plain local git operation, not a call to the stikfix host.)