@akinet/akidevrule 3.4.0 → 3.6.0

package/payload/RULE-release.md

@@ -106,11 +106,7 @@ After updating CHANGELOG and the version bump, produce the GitHub Release withou
 - **Otherwise** (no `gh`, or the user will publish manually) → output the copy-ready block below instead.
 - Before minting, cross-check tags against Releases (`gh release list` vs `git tag`) and offer to backfill any tag that has no matching Release, so the Releases page has no gaps.
 
-**Title:** `v{version}: {2-5 word specific impact}` — no generic words ("patch fixes", "bug fixes", "improvements")
-- Good: `v1.5.1: fix production icons blank, caret, grid gap`
-- Bad: `v1.5.1: patch fixes`, `v1.5.1: various improvements`
-
-**Body:** same `#### Fixed` / `#### Changed` / `#### Added` sections as CHANGELOG, but each bullet trimmed to one short sentence — symptom first, no file paths, no internal jargon.
+**Title and body are B6's tiers, written once:** title `v{version}: {Headline}`, body = the Full tier. Nothing about their wording lives here.
 
 **Compare link (GitHub-hosted repos — mandatory footer):** the notes end with `**Full Changelog**: <repo-url>/compare/<prev-tag>...<new-tag>` — or use `gh release create --generate-notes`, which inserts it automatically. The Release page renders notes only, never a diff, and the tag itself points at a single commit (usually the version-mint commit, a tiny diff) — without this line there is no one-click view of the commits accumulated since the previous release. First release with no prior tag: link `<repo-url>/commits/<new-tag>` instead.
 
@@ -133,10 +129,32 @@ Do not report a plan, task, or release/deploy as complete when a migration/infra
 4. **REHEARSE from the PREVIOUS state, never from empty.** A test or dry-run that starts from a fresh database exercises `CREATE`, not the migration, and proves NOTHING about an upgrade. REQUIRED evidence: the migration executed against (a) a schema generated or snapshotted from the previous release, AND (b) for any data-dependent change (unique index, `NOT NULL` backfill, type change, dedupe) a COPY of real target data. State which was run and quote its output. "The tests pass" is not evidence.
 5. **POSTCONDITIONS asserted, ROLLBACK named.** After the real run, assert expected columns, indexes and row counts by query (condition 1 above), and record the backup or fix-forward path BEFORE any destructive step ([[RULE-agent-behavior]] B3). A migration with no stated rollback or fix-forward path does NOT ship.
 
-### B6. Content discipline
-- Release note copy: no em/en dash (`—` `–`); short user-facing sentences, benefit first. See [[RULE-content-write]].
-- Keep terminology stable across versions (e.g. always "Release Notes", not mixed synonyms). See [[RULE-content-write]] semantic stability.
-- Doc/version moves are part of the change, not an afterthought. See [[RULE-docs]].
+### B6. Release copy — one user-facing text per release, three lengths, printed by default
+The developer record and the user-facing copy are two channels (C1); this item owns the user-facing one for every project type, and every surface that shows a release to a person renders it: the GitHub Release (B4), `releases.json` (C2, web only), an in-app "what's new", a store listing, a post or notification the owner sends by hand. One source, three lengths, all telling one story (`biz.C4`):
+- **Headline** — at most 12 words naming the one thing the user gets: the C2 highlight when there is one, else the most user-visible change. It is the GitHub Release title after `v{version}: ` (A3: the `v` is render-time only) and the `releases.json` `title`. Good: `fix production icons blank, caret, grid gap`; bad: `patch fixes`, `various improvements`, `bug fixes`.
+- **Short** — one or two sentences for a post, a notification, a chat message: the headline's benefit, the concrete mechanism as proof, the link. Says nothing the Full tier does not.
+- **Full** — the highlight first as its own line, then every other change as one sentence each, grouped under C1's sections in C1's order, symptom first for fixes; the compare-link footer per B4 when GitHub-hosted.
+Wording in every tier: benefit first, then proof (`biz.C1`); what the user can now do, never the file, route, symbol or component; no em/en dash, short sentences (`content.B2`); the audience's language per C1's table (English default, plus Vietnamese where the product is bilingual); one canonical term per concept across versions ("Release Notes", never a synonym — `content.A3`). Internal-only work is one honest line ("under-the-hood improvements…", C3), never dressed as a feature.
+**Choosing the headline — a protocol with a written verdict, never a feeling.** The agent that wrote the code is the worst judge of what users gained: it ranks by effort spent, by what landed last, or by what the owner talked about most, and none of those is value. So the choice is made from the user's side, in five steps, and the reasoning is written into the run's receipt where the owner can overrule it:
+1. **Candidates** — every change in the accumulation that alters what a user can do: a new tool, page, mode, format, integration, or an option inside one. `fixed` and `internal` are excluded by construction; a fix that unblocks a core flow may become the *Headline* when nothing else qualifies, but it is never a `highlight` (C2), because the highlight tier means capability gained, not capability restored.
+2. **Three kill-tests per candidate, from the primary audience's seat** (`docs/biz/`, `biz.A1`; when no audience is recorded, the person the product's front page addresses). *Return:* would someone who last used the product before this version come back, or use it differently, because of this? *Tell:* can it be said in one sentence that person would repeat to a peer, with a concrete verb and no file, route, component or internal term? *Before/after:* is there something they could not do before, or could only do with a workaround? A polish, copy, layout or speed change fails the third unless it removes a workaround; an admin-only or owner-only capability fails the first; a candidate whose Tell sentence needs internal vocabulary fails the second. One failed test disqualifies.
+3. **Rank survivors by reach × delta**, both estimated and labeled so: reach is how many of that audience meet it in a normal session (every session > a common task > a niche path); delta is the size of the gain (a new tool or mode > a new option inside an existing tool > a removed workaround).
+4. **Cut to one.** A second only when it is independent of the first (a different job, not a sub-feature of it) and ranks close; three never — a third means the release bundled two releases (A5 materiality) or the ranking is undecided, and undecided resolves to one, not two. Zero survivors is a normal result: the Headline then names the most user-visible fix or change, and the announce verdict is judged on that.
+5. **Cross-check the surfaces before writing.** The Headline, the first `changes[]` line, the `highlight` flag, the Short tier and the GitHub Release title must all point at the same thing; when the title you would naturally write names something the highlight does not, the selection is wrong, not the title. Then write the verdict into the receipt: one line per candidate — `highlight: <thing> — passes return/tell/before-after, reach every session, delta new mode` or `rejected: <thing> — fails return (admin-only)` — so a `release_lint.py` `[HILITE]` line is answered by this record and the owner can overrule a choice without re-deriving it.
+
+**Announce verdict.** The copy ends with `Announce: yes` when the version carries a highlight or a fix the user would notice, or `Announce: no — <reason>` for an internal-only or invisible-fix accumulation: a follower who reads three "stability improvements" posts in a week stops reading the fourth, so the materiality test (A5) applies at the channel too. Channels are the project's own, read from `docs/biz/`, the project `CLAUDE.md` or an existing post history — never invented; with none recorded the verdict stands alone.
+**Where it is produced.** Every `/akiship` run ends with this block, a deferred version included (`deferred — no copy`), and any other run that mints a version prints it in its closing report. It is reused, never rewritten: the `releases.json` entry and the GitHub Release body already are this copy, so the block quotes them rather than composing a third variant; where neither exists (CLI, desktop app without a GitHub Release) the block is the copy's only home and the owner pastes it where it goes.
+
+```
+## Release copy — {version} ({date})
+Headline: …
+Short: …
+Full:
+…
+Announce: yes | no — <reason>
+```
+
+Doc/version moves are part of the change, not an afterthought ([[RULE-docs]]).
 
 ### B7. Pre-ship gate — work finished, nothing pushed yet
 
@@ -154,7 +172,7 @@ Run in order; each step names the rule that owns it.
 1. **Release state** — derive it cold from the repo per B1, never from session memory. `Drifted` blocks everything until A5's recovery has run.
 2. **Hygiene sweep — scoped to the accumulation, never the whole repo.** On the files touched since the boundary commit (B1.5): scythe `[WRAP]`/`[YAP]` lint ([[RULE-agent-behavior]] §0), dead code / redundant guards / duplication the accumulation itself introduced (`pattern.A8`; subtract-class detectors at diff scope), and doc references in touched comments still resolving ([[RULE-docs]] B3). A repo-wide subtraction or zero-trust sweep is a separately scheduled audit, never a per-release cost — diff scope is what keeps this gate affordable at many releases per day. Unlike an audit, findings here are fixed in place: this is a gate, not a report.
 3. **Migration & external-action completeness — the B5 detector runs FIRST, on EVERY release, without exception.** Paste its output (or `empty`) into the receipt. A hit obliges a written answer to each of B5 points 2–5: is it separate, is the order expand → migrate → deploy → contract, was it rehearsed from the PREVIOUS state (which one, quoted output), are postconditions and rollback stated. Startup-embedded migration code counts. Then every other change whose "done" lives outside the repo (remote config, env vars, cron registrations, cache purges) is confirmed live, and each script sits in its completion location ([[RULE-coding]] B3). A green build proves nothing about the database; a green test on an empty database proves nothing about an upgrade.
-4. **Record truthfulness** — every closed problem has its `CHANGELOG.md` entry, and no entry claims something step 3 has not cleared (B2). Web stacks additionally need `releases.json` parity (C3).
+4. **Record truthfulness** — every closed problem has its `CHANGELOG.md` entry, and no entry claims something step 3 has not cleared (B2). Web stacks additionally need `releases.json` parity (C3). Shape is mechanical: `python3 ~/.claude/skills/akiflow/scripts/release_lint.py --latest .` (C4) must exit 0; a `[HILITE]` review line is answered in writing per C2, never silently passed.
 5. **Doc sync — every record surface the accumulation touched, not only `docs/`.** Enumerate, then check each against the diff: plans whose work shipped moved to `docs/plan/done/`; `arch`/`feat` docs match what is about to ship ([[RULE-docs]] B1, B3); `README.md` wherever the accumulation changed setup, commands, layout, or a documented behavior; the project's task-note file when one exists (`.akidevsync/notes.json`, edited only through the `akidevsync-notes` skill — a note whose fix is in this accumulation is marked done with the matching CHANGELOG line, an unmatched or unverified one stays open and is named in the report); and any external standards doc the project `CLAUDE.md` binds the project to, updated in place when the accumulation changed a convention that doc owns. A surface skipped because it was not in `docs/` is the same drift finding as a stale doc.
 6. **Build & test — mirror CI.** Commands are derived, never invented: the jobs `.github/workflows/*` run on push/tag take priority; a repo with no such workflow falls back to the manifest's own scripts (`npm run typecheck`/`build`/`test`, `cargo build`/`cargo test`, equivalent). Run every one of them locally, self-authorized ([[RULE-coding]] B3 — ship/release is the moment full build+test is mandatory, not optional). A failure blocks the gate and is fixed in place, same as step 2. A CI step that cannot be reproduced locally (an other-OS matrix leg, a job needing secrets) is named explicitly and left to B10 to catch post-push. A repo with no build/test command at all says so plainly — that is a finding, not a silent pass. This step sits after 2–5 because those fix code and docs first, and the build must cover what is actually about to ship.
 7. **Verification honesty** — anything only checkable at runtime is reported as unverified rather than assumed ([[RULE-coding]] B3). "Untested but I expect it works" is a valid gate output; a silent "Done" is not.
@@ -176,8 +194,8 @@ The B7 gate plus its surrounding ritual (fix findings → sync docs → CHANGELO
 ### B9. Registry-published package (npm, crates.io, PyPI, …) — the registry version is the release
 
 A package installed from a registry is a distributed artifact (A5): users get what the registry serves, so a tag plus GitHub Release with no registry version leaves `npx`/`pip install` on the old one. Released = tag + GitHub Release + `npm view <pkg>@<version> version` (or the registry's equivalent) returning the new version (`coding.B3`).
-- **The publish mechanism is derived, never designed.** Read the existing convention first: project `CLAUDE.md`, `.github/workflows/`, and sibling packages the same account already publishes (`npm access list packages`) — a working sibling is the template (`coding.B5` rung 2). A CI publish job with a registry token adds a secret and automation: `agent.B3` territory, never the default.
-- **Account facts are probed, not inferred** (`coding.B5` rung 5): `npm whoami` (session), `npm org ls <scope>` (scope ownership — a 404 on the package name means the name is unpublished, never that the scope is unowned), `npm profile get` (2FA mode).
+- **The publish mechanism is derived, never designed.** Read the existing convention first: project `CLAUDE.md`, `.github/workflows/`, and sibling packages the same account already publishes (`npm access list packages`) — a working sibling is the template (`coding.B3` rung 2). A CI publish job with a registry token adds a secret and automation: `agent.B3` territory, never the default.
+- **Account facts are probed, not inferred** (`coding.B3` rung 5): `npm whoami` (session), `npm org ls <scope>` (scope ownership — a 404 on the package name means the name is unpublished, never that the scope is unowned), `npm profile get` (2FA mode).
 - **2FA `auth-and-writes` makes `npm publish` the run's single hand-off** (rung 6: the OTP is human-held). Everything else is agent work — push, tag, GitHub Release, tarball verification — so the owner receives one command and the `npm view` check that proves it landed, never a list of prerequisites.
 - **A published version number is burned forever** (`npm unpublish` is time-limited and a number is never reusable), so verify the tarball before publishing: `npm pack --dry-run` against the `files` allowlist, manifest version == CHANGELOG top == tag (A3), and the `bin` executed from the packed tarball installed in the scratchpad. A `bin` that writes to `$HOME` takes the override on its own command — `printf y | HOME="$SANDBOX" bin`, never `HOME="$SANDBOX" printf y | bin`, which scopes the variable to `printf` and runs against the real home.
 
@@ -204,17 +222,20 @@ After ANY deploy or restart, in any flow (not only `/akiship`), verify FUNCTION,
 ### C1. Two separate channels — do not merge them
 | File | Audience | Language | Tone |
 |------|----------|----------|------|
-| `CHANGELOG.md` | developer / technical | English only | Precise, may name files/symbols. Keep a Changelog format (`Added` / `Changed` / `Fixed` / `Removed`) |
+| `CHANGELOG.md` | developer / technical | English only | Precise, may name files/symbols. Keep a Changelog shape, closed and ordered — see below |
 | `app/data/releases.json` | public / end user | Bilingual EN + VI if the site is multilingual (default EN); EN-only if single-language | Popular, user-friendly, benefit-first. No jargon, no file paths |
 
 The changelog explains *what changed and why* for maintainers. The release note tells users *what they get*. Write them separately; do not paste changelog lines into the release note.
 
+**CHANGELOG shape — one canonical form, mechanically checked (`release_lint.py`, C4).** Version heading `## [x.y.z] - YYYY-MM-DD` (`## [Unreleased]` while open), sections `### <Name>` at exactly one level below, each at most once per version, in this fixed order and from this closed vocabulary: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. Sections that ship nothing are omitted, never left empty. There is no `Internal`, `Docs`, `Notes`, `Verified`, `Refactored` or any other heading: internal, tooling and docs work is `Changed`; a verification or caveat is a clause on the bullet it qualifies; a decision's reasoning lives in the bullet or in `docs/research/`. The order is the standard's, not importance-ranked: an order chosen per release is unobservable across releases and drifts the moment two people, or two sessions, write entries. Evidence: 21 of 25 audited projects had entries out of order, 9 distinct orderings within one file, 13 invented headings across the set, and this rule itself named two different orders in two sections.
+
 `releases.json` exists **only where a public web page renders it** (the Nuxt stack's release-notes page). Tauri, CLI, and other non-web projects keep `CHANGELOG.md` only — a release-notes file nothing renders is dead data; do not create one. Where `releases.json` does not exist, every rule below that mentions it simply does not apply.
 
 ### C2. releases.json schema
 - Single-language site: `{ version, date, title, changes: [{ type, text }] }`
 - Multilingual site: localize the human text — `title: { en, vi }`, `changes: [{ type, text: { en, vi } }]`. Keep `version`, `date`, `type` locale-neutral. Default/fallback language is English.
 - `type` is one of `new` | `improved` | `fixed` | `internal` (stable badge keys).
+- `highlight: true` (optional, locale-neutral) marks the line B6's headline protocol selected — a capability gained, chosen from the primary audience's seat through the three kill-tests and the reach × delta ranking, with the verdict written in the run's receipt. It is a tier, never a filter: every change still ships as a line (C3); the page renders the highlighted line as a distinct card, because a flat list gives a bug fix and a new tool the same weight, so the reader's eye has nothing to land on and the page reads as a log, not a product moving. Shape: the highlighted line is the **first** in `changes[]`; at most one, two only when B6 step 4 allows it; never on `fixed` or `internal`; zero is correct when no candidate survives. The `title` is B6's Headline tier and names the same thing the highlight marks (one story per surface, `biz.C4`); a title that headlines something the highlight does not, or vice versa, means one of them is wrong. Write the highlighted line benefit-first with the concrete mechanism as proof (`biz.C1`, `content.B2`): what the user can now do, then how — never the file, route or component that does it. Mechanical review: `release_lint.py` emits `[HILITE]` for a version with a `new` change and no highlight — a candidate, answered by B6 step 5's per-candidate verdict lines in the gate receipt, never silently passed.
 
 ### C3. No version gaps, and no content gaps, in releases.json
 Every version that appears in `CHANGELOG.md` MUST also appear in `releases.json` (no missing version), and every `Added`/`Changed`/`Fixed`/`Removed` section in that version's CHANGELOG entry must be represented by at least one `changes[]` line in `releases.json` (no missing content) — skipping a version, or silently dropping a whole category of its work, because it reads as "internal" or "technical" is not allowed. This page is the one place both a human visitor and a crawling/LLM bot judge whether the product is actively maintained; a version that reads as empty is worse than one that reads as unglamorous.
@@ -228,14 +249,13 @@ Every version that appears in `CHANGELOG.md` MUST also appear in `releases.json`
 Never leave a gap like `1.0.5 → 1.0.7` or `0.1.0 → 0.1.3` in releases.json. A one-line entry is better than a missing version.
 
 ### C4. Sync check — required before closing a task
-After editing `CHANGELOG.md` or `releases.json`, run:
+After editing `CHANGELOG.md` or `releases.json`, run from the project root:
 
 ```
-grep '"version"' app/data/releases.json
-grep -E '^## \[' CHANGELOG.md
+python3 ~/.claude/skills/akiflow/scripts/release_lint.py --latest .
 ```
 
-Confirm every CHANGELOG version has a matching entry in releases.json and the order (newest-first in releases.json, newest-first in CHANGELOG) is consistent. Fix any gap before the task is done.
+Exit 0 is the pass. Verdict tags — `[ORDER]`, `[SECTION]`, `[LEVEL]` (C1 shape), `[PARITY]` (a version in one surface and not the other, C3), `[TYPE]` (a badge key outside C2) — are fixed before the task closes. `[HILITE]` is a review line (C2), answered, never auto-fixed. Without `--latest` the script sweeps every version — that is an audit run (`agent.B5`), never a per-task cost; historical entries are corrected only when a task already touches them, never as a backfill sweep.
 
 ### C5. Live production verification
 Never trust a deployment CLI's success status alone. A web deploy is only verified when the live production URL explicitly returns the new version data.

package/payload/RULE-seo.md

@@ -1,6 +1,6 @@
 # SEO Rule — Nuxt + Cloudflare Stack
 
-<!-- Address map: seo.A1-5 · seo.B1-4 · seo.C1-3 (⟨Aki⟩) -->
+<!-- Address map: seo.A1-6 · seo.B1-3 · seo.C1-3 (⟨Aki⟩) -->
 
 ## Scope
 Cross-project rules for all Nuxt 4 + Cloudflare Pages sites. For project-specific keyword strategy and schema values, see the project's own `docs/ref/seo.md` or equivalent.
@@ -78,6 +78,15 @@ sitemap: {
 - **Location**: `public/ogimage/[slug].jpg` or `.png`
 - **Fallback**: if page-level image is absent, the composable falls back to the site-wide default OG image
 - Never reference an OG image path that doesn't exist in `public/`
+- Referenced site-relative (`/ogimage/slug.jpg`); the SEO composable makes it absolute (A6)
+
+### A6. URL form — relative at rest, absolute only at emission
+
+- Every same-site URL is stored and rendered root-relative (`/images/x.jpg`, `/path/`): content data, internal links, `<img src>`/`srcset`, asset references. An own-origin literal (`https://domain.com/...`) there breaks localhost and preview deploys, and hides a missing local asset behind the production copy.
+- Consumers that require an absolute URL (`og:image`, `twitter:image`, `og:url`, canonical, hreflang, JSON-LD `url`/`image`/`logo`, sitemap, RSS, email, share text) get it from one helper at the emission boundary (SEO composable, schema builder, feed generator), never from the stored value. The helper is idempotent (relative → absolute, absolute → unchanged), so legacy absolute data keeps working without a migration.
+- The origin comes from the one configured site URL (`pattern.A1`), never from the request host: a preview deploy must still emit production canonical and OG URLs.
+- A subpath deploy (`baseURL` ≠ `/`) prefixes through the framework's base-URL mechanism, never by string concatenation per call site.
+- Detected mechanically in C3.
 
 ## B. AI visibility & entity
 
@@ -91,7 +100,7 @@ These rules help content appear in AI-generated answers (Perplexity, ChatGPT, Ge
 - **alternateName in Organization/WebSite schema**: include all brand spelling variants (accented + unaccented + lowercase + domain form) so AI can resolve them to a single entity
 - **knowsAbout**: list the topics the brand covers — helps AI cite the site as a relevant source
 
-> ⚠️ **`llms.txt` is not an AI-visibility strategy (2026).** A log study across 137,000 domains found **97% of `llms.txt` files received zero requests over a full month**; no major LLM vendor has committed to reading the format, and Google's John Mueller has compared it to the meta keywords tag — a standard proposed by publishers that no consumer agreed to honour. Keep the file if it already exists (it costs nothing and is genuinely useful for *internal* agents reading the site), but never list it as an SEO/GEO deliverable and never let it substitute for the thing that does work: getting the content into the server-rendered HTML (B4).
+> ⚠️ **`llms.txt` is not an AI-visibility strategy (2026).** A log study across 137,000 domains found **97% of `llms.txt` files received zero requests over a full month**; no major LLM vendor has committed to reading the format, and Google's John Mueller has compared it to the meta keywords tag — a standard proposed by publishers that no consumer agreed to honour. Keep the file if it already exists (it costs nothing and is genuinely useful for *internal* agents reading the site), but never list it as an SEO/GEO deliverable and never let it substitute for the thing that does work: getting the content into the server-rendered HTML (B3).
 
 ### B2. Entity & ecosystem linking
 
@@ -103,16 +112,7 @@ For sites that belong to a multi-site ecosystem or brand family:
 
 Keep the concrete domain list (parent org URL, sibling sites) in the project's own docs — one source of truth per ecosystem, not hardcoded in shared rules.
 
-### B3. Vietnamese keyword handling (vi locale)
-
-Google treats accented and unaccented Vietnamese as different queries (`vst là gì` ≠ `vst la gi`). To cover both without degrading UX:
-
-- **Embed the unaccented form in parentheses** in the first mention of a term in body copy or FAQ: *"...VST (vst la gi)..."*
-- **Or include it in** `keywords` meta or `alternateName` in schema
-- **Never** put unaccented forms in H1, H2, visible headings, or the FAQ question text — it looks unprofessional
-- **Meta title and description**: use correctly accented Vietnamese; unaccented coverage comes from schema + body copy
-
-### B4. Prerendering & SSR
+### B3. Prerendering & SSR
 
 - SEO-critical content must be in the HTML at crawl time — not injected by client-side JS. **This is the single highest-evidence rule in this file for AI visibility**: roughly 69% of AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, Claude-SearchBot, PerplexityBot) do **not** execute JavaScript, so a client-only SPA is simply invisible to them. Googlebot and Gemini do render; ChatGPT, Claude and Perplexity do not. Prerendering beats every schema tweak combined.
 - Public pages: prerender/SSG preferred
@@ -129,7 +129,7 @@ Every public page must call `usePageSeo()`. Canonical URL is derived automatical
 usePageSeo({
   title: 'Page Topic',               // Max 60 chars total — NO brand suffix (see @nuxtjs/seo note below)
   description: 'Action-oriented…',   // Max 155 chars, unique per page
-  ogImage: 'https://domain.com/ogimage/slug.jpg',  // optional
+  ogImage: '/ogimage/slug.jpg',      // optional, site-relative — the composable absolutizes it (A6)
   ogImageAlt: 'Description of image',              // optional
   noindex: true,                      // optional, for admin/private pages
 })
@@ -161,6 +161,8 @@ Run `scripts/validate-seo.js` (or equivalent) after every build. At minimum it s
 - [ ] All descriptions ≤ 155 chars
 - [ ] No em dash (`—`) or en dash (`–`) in title or description
 - [ ] All canonical URLs end with `/`
+- [ ] No rendered `src`, `srcset` or `<a href>` carries the site's own origin (A6); `<head>` `link`/`meta` are exempt, they are emission targets
+- [ ] Every `og:image`, `twitter:image` and JSON-LD `image` is an absolute `https://` URL
 - [ ] Homepage `Organization` schema has `alternateName` and `sameAs`
 - [ ] `/admin/**` pages absent from sitemap output
 - [ ] Skip redirect stub files (`http-equiv="refresh"`) — they have no SEO content to validate

package/payload/RULE-stack-akiNuxtCf.md

@@ -27,6 +27,7 @@ Nuxt 4 · Vue 3 · Tailwind v4 · @nuxtjs/i18n · @nuxtjs/seo · SweetAlert2 ·
   - `crypto.subtle` operates on bytes — feed it `new TextEncoder().encode(str)`, not the string.
 - Do not enable `nodejs_compat` in `wrangler.toml` unless upstream issues are confirmed fixed
 - Trailing slash: `trailingSlash: true` everywhere (routing, canonical, og:url, sitemap, schema.org) — canonical config lives in the i18n section below
+- Site origin: `site.url` in `nuxt.config` is the single source, read through `useSiteConfig().url` (nuxt-site-config, bundled with `@nuxtjs/seo`) inside the one URL helper the SEO composable and schema use; never a `'https://domain'` literal in a composable, page, component or content record. URL form: `seo.A6`
 - Never call h3's `readBody()` in a DELETE handler. On workerd, reading a body the runtime never actually attached to a DELETE request hangs the promise instead of rejecting it — the platform then kills the request as a bare 500 with no stack trace. This reproduces on real Cloudflare Pages/Workers but NOT under `nuxt dev` (Node), so it survives local testing and only surfaces in production. Pass the id (or any DELETE payload) via query string on both client and server instead — never body.
 - After the response, keep the isolate alive with `event.context.cloudflare.context.waitUntil` (the path live notify modules use on tachnhac / vstshop / tuvi / kinhdich). Nitro 2.13 also wraps the same CF context as `event.waitUntil`. Do not copy Nitro v3 docs onto this stack: v3 puts the platform on `event.req.runtime.cloudflare`, and `event.req.waitUntil` does not exist on 2.13, so the isolate dies. `nuxt dev` cannot prove isolate lifetime. A 200 that returns before the background work is not evidence the work ran.
 

package/payload/RULE-stack-tauri.md

@@ -56,4 +56,4 @@ Three switches, routinely confused — pick by what each actually controls:
 - **Ad-hoc signing loses the grant on every rebuild.** `codesign --sign -` (Xcode's "Sign to Run Locally") produces a new signature each build, and the authorization is tied to that exact build — so a permission granted yesterday is simply gone today, which reads as a random TCC bug. The fix is a **stable self-signed certificate**, which keeps grants across rebuilds; `tccutil reset All <bundle-id>` only clears the stale state, it does not prevent the next loss.
 - **Scope limit — this chain governs consent-based reads.** It does not apply to paths the user picked in an Open/Save dialog or by drag-and-drop (user intent grants access directly), and Apple's own analysis excludes file *writes* from it. A write-only or file-picker-driven sidecar failing is a different diagnosis; don't reach for these switches first.
 
-When you cannot tell which switch fired, watch it rather than guess: `log show --predicate 'subsystem == "com.apple.TCC"' --last 5m` prints the `AttributionChain` (which process was held responsible) and the request's result. Claims and sources: `docs/research/macos-tcc-tauri-boundary-aug21.md` in the akidevrule repo. Full lookup (switches + rebuild/DR mechanism): `~/.aki/akidevrule/docs/ref/macos-codesign-tcc.md`.
+When you cannot tell which switch fired, watch it rather than guess: `log show --predicate 'subsystem == "com.apple.TCC"' --last 5m` prints the `AttributionChain` (which process was held responsible) and the request's result. Claims and sources: `docs/research/macos-tcc-tauri-boundary-aug21.md` in the akidevrule repo. Full lookup (switches + rebuild/DR mechanism): `~/.aki/akidevrule/docs/ref/fact-macos-codesign-tcc.md`.

package/payload/RULE-ui-pattern.md

@@ -11,6 +11,7 @@
 - **Composition over duplication (Law 5)** → slots / dynamic components / `v-for`, never hand-copied markup.
 - **OCP (Law 4)** → extend a component via props / variant / slot, never fork a copy.
 - **Name by role (Law 7)** → semantic tokens and variants, never value-names.
+- **Draft, then commit once (Law 9)** → `dragenter`/`dragover`/`pointermove`/`input` handlers touch a local draft only; `drop`/`pointerup`/`Enter`/Save writes the store once. Grep: no store setter, `localStorage`, IPC or fetch inside a preview handler.
 - **Reshape, don't stack (Law 8)** → before packaging a repeated style, try to remove it. The tier ladder only *packages* repetition; Law 8 is the only thing that *eliminates* it, and without it a codebase obeys every rule here while growing without bound.
 - **Documentation** → every global pattern is looked up before writing and recorded after, so the next agent reuses instead of rewriting.
 

package/skills/aki-article-writer/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: aki-article-writer
 description: >-
-  Per-project article writing skill: research & fact-verification, SEO metadata,
-  JSON-LD schema generation, UX-psychology-aware content, and a separate Image Scout
-  subagent (Gemini Flash / Haiku) for image search, download, visual inspection,
-  slug-named processing, and WebP output. Activate when the user asks to write a
-  new article, create content, draft a blog post, or produce a knowledge entry for
-  any project.
+  Per-project pipeline for publishable site prose: research & fact-verification, SEO
+  metadata, JSON-LD, UX-psychology-aware content, a rendered-output pass, and a
+  separate Image Scout subagent for images. Activate whenever the task writes,
+  rewrites, translates or reviews an article, news or blog post, announcement or
+  knowledge entry for any site, in any wording or language, including turning a
+  release, changelog or finding into a post.
 ---
 
 # aki-article-writer
 
-Invoke with `/aki-article-writer`, or whenever the user asks in any wording for an article to be written.
+Invoke with `/aki-article-writer`, or whenever a task writes, rewrites, translates or reviews publishable site prose (article, news/blog post, announcement, knowledge entry), in any wording — including a release or finding to be turned into a post.
 
 This skill delegates one full article to a dedicated **Article Worker subagent**. The worker spawns a separate **Image Scout subagent** (lightweight model) for all image work, keeping both agents' contexts clean and independent.
 

package/skills/aki-article-writer/references/article-workflow.md

@@ -92,7 +92,7 @@ Select the correct schema type based on project:
 
 ### 2.5 URL canonical & trailing slash
 
-All canonical URLs, sitemap entries, `og:url`, internal links, and JSON-LD `url` fields must end with `/`. Required for Cloudflare Pages compatibility.
+All canonical URLs, sitemap entries, `og:url`, internal links, and JSON-LD `url` fields must end with `/`. Required for Cloudflare Pages compatibility. Those absolute URLs are produced at emission; every URL stored in the record or rendered in the body is site-relative (`seo.A6`).
 
 ---
 
@@ -130,16 +130,7 @@ Example:
 
 Use exactly one canonical term for each concept throughout the article. Synonym variation may seem stylistically rich but confuses both readers and AI crawlers. Pick the term, define it once, use it consistently.
 
-### 3.4 Vietnamese dual-coverage (vi locale)
-
-Google treats `vst là gì` and `vst la gi` as different queries. To cover both without degrading readability:
-
-- Embed the unaccented form in parentheses at its **first occurrence** in body copy or FAQ: `…VST (vst la gi) là loại phần mềm…`
-- Or place it in `keywords` meta or `alternateName` in schema
-
-**Never** place unaccented forms in H1, H2, H3, or FAQ question text — it degrades the visual quality of the interface.
-
-### 3.5 Anxiety handling at CTA
+### 3.4 Anxiety handling at CTA
 
 At every call-to-action point (sign-up, purchase, download, consult), identify the dominant user anxiety at that moment and answer it right there — not on a distant FAQ page:
 
@@ -150,12 +141,12 @@ At every call-to-action point (sign-up, purchase, download, consult), identify t
 | Compatibility | "Hỗ trợ Win/Mac, tương thích mọi DAW phổ biến" |
 | Privacy | "Không lưu dữ liệu cá nhân, xoá tài khoản bất cứ lúc nào" |
 
-### 3.6 Internal & external links
+### 3.5 Internal & external links
 
 - **Internal links:** ≥ 2 links to related articles or service pages within the same project
 - **External links:** link to authoritative sources when citing data; add `rel="noopener"`
 
-### 3.7 SSR / prerender requirement
+### 3.6 SSR / prerender requirement
 
 69% of AI crawlers (ChatGPT, ClaudeBot, PerplexityBot, OAI-SearchBot) do not execute JavaScript. All article content, meta tags, and schema must be present in the server-rendered HTML at crawl time — never client-side only.
 
@@ -331,7 +322,7 @@ Embed with markdown image syntax directly in body content:
 ### `article_arch: component` (single-image mode)
 
 Do **not** write `![]()` anywhere in body/paragraph fields — the renderer does not parse it and will print the literal text. Instead:
-1. Set the content record's existing share-image field (e.g. `ogImage`) to `/images/articles/<slug>.<ext>`.
+1. Set the content record's existing share-image field (e.g. `ogImage`) to `/images/articles/<slug>.<ext>`, site-relative. Confirm the SEO composable and schema make it absolute (`seo.A6`); if either passes it through raw, fix that helper once — never write the site origin into the record, even when neighbouring records do.
 2. Confirm the shared render component (e.g. `ContentArticle.vue`) already displays that field as a hero image above the body. If it does not yet, that is a one-time component change to flag to the user — do not route around it with markdown text in a paragraph.
 3. No separate body images in this mode; one image serves as both hero and OG/share image.
 
@@ -354,7 +345,6 @@ Article Worker runs through the full checklist before reporting completion.
 - [ ] No `UNVERIFIED` claim appears in the published text
 - [ ] No banned openers in any paragraph or FAQ answer
 - [ ] No paragraph exceeds 5 lines
-- [ ] Unaccented Vietnamese keyword embedded in parentheses at first occurrence in body / FAQ (vi locale only)
 - [ ] CTA point has an anxiety-answering line
 - [ ] ≥ 1 H2 is a direct question (ends with `?`)
 - [ ] ≥ 2 internal links
@@ -370,6 +360,12 @@ Article Worker runs through the full checklist before reporting completion.
 ### 6.4 SSR / prerender
 - [ ] Article content, meta tags, and schema are present in server-rendered HTML, not deferred to client-side JS
 
+### 6.5 Rendered-output pass
+Source strings, a green build and a passing SEO validator do not show what the reader sees. After the build, open the article's built HTML (every locale) — the build is self-authorized, no dev server needed (`coding.B3`):
+- [ ] `grep` the page body: no `src`, `srcset` or `<a href>` carries the site's own origin; `og:image` and JSON-LD `image` are absolute (`seo.C3`)
+- [ ] Read the full rendered text top to bottom as the target reader, in each locale, and fix anything that reader would stumble on — before reporting the article done
+- [ ] Any SEO device visible in the text (a parenthetical keyword variant, a repeated keyphrase) is listed as a review line, never shipped silently
+
 ---
 
 ## Antigravity / AGY note

package/skills/akiflow/SKILL.md

@@ -212,7 +212,7 @@ python3 ~/.claude/skills/akiflow/scripts/council_cost.py --session <uuid>
 - **Claude Code:** roster in one batch; `SendMessage` for peer challenge and for resuming completed seats; continuity travels as the plan doc or diff named in the prompt, since the one `subagent_type` that inherits session history (`fork`) is gated off by default; `isolation: "worktree"` for concurrent writers. An agent the *user* stopped refuses to resume via message and must be resumed from its own transcript panel — do not respawn a duplicate.
 - **Headless (`claude -p`):** nobody can answer an escalation or a permission prompt. Record it as `BLOCKED: needs owner` in `checklist.md` and continue the other items — never guess what the owner would have wanted.
 - **Antigravity / AGY:** supports native subagents via `invoke_subagent`. When `/akiflow` is invoked with multiple experts or dispatch lanes, the lead MUST spawn the roster via `invoke_subagent` concurrently in one batch. Simulating multiple seats sequentially in a single session context without spawning real subagents is strictly forbidden (role collapse / self-approval violation). Where AGY is reachable from a Claude Code lead, it may also serve as a wide-context worker substrate (`aki-hands`).
-  - **Script paths in this skill's literal commands are written for Claude Code** (`~/.claude/skills/akiflow/scripts/...`). This file is deployed byte-identical to `~/.gemini/config/skills/` too (`docs/ref/agent-skills-standard.md`), so either root's path runs the same script under Antigravity/agy. **Run the command exactly as written above** — the installer pre-allows both roots in both renderings (expanded and tilde-literal), so the form you copy is never what gets denied. Background: agy's matcher compares command strings literally, with no glob or tilde expansion, so a rule and a command that render the same path differently do not match — which is why the pre-allow covers every rendering instead of asking you to normalize one (`docs/ref/cli-permission-allowlist-standard.md` §1.2).
+  - **Script paths in this skill's literal commands are written for Claude Code** (`~/.claude/skills/akiflow/scripts/...`). This file is deployed byte-identical to `~/.gemini/config/skills/` too (`docs/ref/fact-agent-skills-standard.md`), so either root's path runs the same script under Antigravity/agy. **Run the command exactly as written above** — the installer pre-allows both roots in both renderings (expanded and tilde-literal), so the form you copy is never what gets denied. Background: agy's matcher compares command strings literally, with no glob or tilde expansion, so a rule and a command that render the same path differently do not match — which is why the pre-allow covers every rendering instead of asking you to normalize one (`docs/ref/fact-cli-permission-allowlist-standard.md` §1.2).
 
 Verified harness facts behind every flag named here: `references/harness-facts.md` — its § Worker invocation quick-facts is the lookup table (literal command, read-only mechanism, silent failure per lane); the rest of the file is why. Design record: `docs/arch/akiflow.md` in the akidevrule repo.
 

package/skills/akiflow/scripts/release_lint.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+# release_lint.py — mechanical checks for the release record surfaces RULE-release.md owns: CHANGELOG.md shape (C1) and releases.json parity + highlight (C2–C4).
+# Usage: release_lint.py [--latest] [--all] <project-dir|CHANGELOG.md> [...]   --latest checks only the newest version block (the B7 gate scope).
+# Output: [TAG] path:line | short label      Exit: 0 clean · 1 findings · 2 usage error.   Same grammar as scythe.py.
+# Verdict tags: [ORDER] sections out of canonical order · [SECTION] heading outside the closed vocabulary or duplicated · [LEVEL] version/section heading at the wrong level · [PARITY] version present in one surface and absent from the other · [TYPE] releases.json type outside new|improved|fixed|internal.
+# Review tag (never a verdict): [HILITE] a version with a `new` change and no `highlight: true` line, more than two highlighted lines, a highlight not first, or a highlight on a `fixed`/`internal` line — a candidate for C2 judgment.
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+
+SECTIONS = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']
+TYPES = {'new', 'improved', 'fixed', 'internal'}
+HIGHLIGHT_MAX = 2
+
+_VERSION = re.compile(r'^(#+)\s*\[?(v?\d+\.\d+\.\d+[^\]\s]*|Unreleased)\]?', re.I)
+_SECTION = re.compile(r'^(#+)\s*(\S+)')
+
+
+def _changelog_blocks(lines: list[str]) -> list[dict]:
+    """Split a CHANGELOG into version blocks: {version, line, level, sections:[(name, line, level)]}."""
+    blocks: list[dict] = []
+    fence = False
+    for n, raw in enumerate(lines, 1):
+        if raw.lstrip().startswith(('```', '~~~')):
+            fence = not fence
+            continue
+        if fence or not raw.startswith('#'):
+            continue
+        vm = _VERSION.match(raw)
+        if vm and (not blocks or len(vm.group(1)) <= 2 or blocks[-1]['level'] == len(vm.group(1))):
+            blocks.append({'version': vm.group(2), 'line': n, 'level': len(vm.group(1)), 'sections': []})
+            continue
+        sm = _SECTION.match(raw)
+        if sm and len(sm.group(1)) == 2 and sm.group(2) != 'Changelog':
+            blocks.append({'version': None, 'line': n, 'level': 2, 'sections': [], 'heading': raw.lstrip('# ').strip()})
+            continue
+        if sm and blocks and blocks[-1]['version'] and len(sm.group(1)) > blocks[-1]['level']:
+            blocks[-1]['sections'].append((sm.group(2).strip('*').rstrip(':'), n, len(sm.group(1))))
+    return blocks
+
+
+def lint_changelog(path: Path, latest: bool) -> tuple[list[str], list[str], list[str]]:
+    lines = path.read_text(encoding='utf-8', errors='replace').splitlines()
+    all_blocks = _changelog_blocks(lines)
+    blocks = all_blocks[:1] if latest else all_blocks
+    findings: list[str] = []
+    for b in blocks:
+        if b['version'] is None:
+            findings.append(f"[SECTION] {path}:{b['line']} | H2 `{b['heading']}` is not a version heading")
+            continue
+        if b['level'] != 2:
+            findings.append(f"[LEVEL] {path}:{b['line']} | version heading at H{b['level']}, expected `## [{b['version']}] - <date>`")
+        names = [s[0] for s in b['sections']]
+        seen: set[str] = set()
+        for name, n, lvl in b['sections']:
+            if name not in SECTIONS:
+                findings.append(f"[SECTION] {path}:{n} | `{name}` is not one of {', '.join(SECTIONS)}")
+            elif name in seen:
+                findings.append(f"[SECTION] {path}:{n} | `{name}` repeated inside {b['version']}")
+            elif lvl != b['level'] + 1:
+                findings.append(f"[LEVEL] {path}:{n} | section at H{lvl}, expected H{b['level'] + 1}")
+            seen.add(name)
+        std = [x for x in names if x in SECTIONS]
+        if std != sorted(dict.fromkeys(std), key=SECTIONS.index) and len(set(std)) == len(std):
+            expected = ', '.join(sorted(std, key=SECTIONS.index))
+            findings.append(f"[ORDER] {path}:{b['line']} | {b['version']}: {', '.join(std)} — expected {expected}")
+    scoped_versions = [b['version'].lstrip('v') for b in blocks if b['version']]
+    all_versions = [b['version'].lstrip('v') for b in all_blocks if b['version']]
+    return findings, scoped_versions, all_versions
+
+
+def lint_releases(path: Path, changelog_versions: list[str], all_changelog_versions: list[str], latest: bool) -> list[str]:
+    findings: list[str] = []
+    try:
+        data = json.loads(path.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError) as e:
+        return [f"[PARITY] {path}:1 | unreadable releases.json ({e})"]
+    items = data if isinstance(data, list) else data.get('releases', [])
+    if latest:
+        items = items[:1]
+    text = path.read_text(encoding='utf-8').splitlines()
+
+    def line_of(version: str) -> int:
+        for n, raw in enumerate(text, 1):
+            if f'"{version}"' in raw:
+                return n
+        return 1
+
+    json_versions = [str(r.get('version', '')).lstrip('v') for r in items]
+    for v in [x for x in changelog_versions if x.lower() != 'unreleased']:
+        if v not in json_versions:
+            findings.append(f"[PARITY] {path}:1 | CHANGELOG version {v} has no releases.json entry")
+    # Reverse check needs the full history: with [Unreleased] on top, --latest's one block never holds the newest shipped version.
+    for r, v in zip(items, json_versions):
+        n = line_of(v)
+        if v not in all_changelog_versions:
+            findings.append(f"[PARITY] {path}:{n} | releases.json version {v} has no CHANGELOG entry")
+        changes = r.get('changes', [])
+        for c in changes:
+            if c.get('type') not in TYPES:
+                findings.append(f"[TYPE] {path}:{n} | {v}: type `{c.get('type')}` not in {', '.join(sorted(TYPES))}")
+        hl = [c for c in changes if c.get('highlight')]
+        if not hl and any(c.get('type') == 'new' for c in changes):
+            findings.append(f"[HILITE] {path}:{n} | {v}: has a `new` change but no `highlight: true` (review)")
+        if len(hl) > HIGHLIGHT_MAX:
+            findings.append(f"[HILITE] {path}:{n} | {v}: {len(hl)} highlighted lines, more than {HIGHLIGHT_MAX} (review)")
+        if hl and changes and not changes[0].get('highlight'):
+            findings.append(f"[HILITE] {path}:{n} | {v}: highlighted line is not the first change (review)")
+        for c in hl:
+            if c.get('type') in ('fixed', 'internal'):
+                findings.append(f"[HILITE] {path}:{n} | {v}: highlight on a `{c.get('type')}` change, C2 allows only new/improved (review)")
+    return findings
+
+
+def lint_target(target: str, latest: bool) -> list[str]:
+    p = Path(target)
+    changelog = p if p.is_file() else p / 'CHANGELOG.md'
+    if not changelog.is_file():
+        print(f"release_lint: no CHANGELOG.md at {target}", file=sys.stderr)
+        sys.exit(2)
+    findings, versions, all_versions = lint_changelog(changelog, latest)
+    releases = changelog.parent / 'app' / 'data' / 'releases.json'
+    if releases.is_file():
+        findings.extend(lint_releases(releases, versions, all_versions, latest))
+    return findings
+
+
+def main() -> None:
+    latest = '--latest' in sys.argv
+    show_all = '--all' in sys.argv
+    targets = [a for a in sys.argv[1:] if not a.startswith('--')]
+    if not targets:
+        print("usage: release_lint.py [--latest] [--all] <project-dir|CHANGELOG.md> [...]", file=sys.stderr)
+        sys.exit(2)
+    findings: list[str] = []
+    for t in targets:
+        findings.extend(lint_target(t, latest))
+    if not findings:
+        sys.exit(0)
+    cap = 40
+    shown = findings if show_all or len(findings) <= cap else findings[:cap]
+    for line in shown:
+        print(line)
+    if len(shown) < len(findings):
+        counts: dict[str, int] = {}
+        for line in findings:
+            tag = line.split()[0]
+            counts[tag] = counts.get(tag, 0) + 1
+        print(f"--- {len(findings) - cap} more findings suppressed ---")
+        print('  '.join(f"{t} {c}" for t, c in counts.items()) + f"  (total {len(findings)})")
+    sys.exit(1)
+
+
+if __name__ == '__main__':
+    main()

package/skills/akihelp/SKILL.md

@@ -11,14 +11,14 @@ Invoke with `/akihelp`, or whenever the user asks, in any wording, what this set
 
 ## Steps
 
-1. Read `~/.aki/akidevrule/index.md` — the file manifest with tiers and purposes.
+1. Read the Routes table in `~/.claude/skills/akirule/SKILL.md` — one row per rule file: its topic, when it loads, its signals. `RULE-agent-behavior.md` is the one resident rule and is not in the table.
 2. List `~/.claude/skills/` and read the frontmatter (`name` + `description`) of each skill whose directory is prefixed `aki` — these are the installed Aki skills.
 3. List `~/.claude/agents/` and read the frontmatter (`name` / `description` / `tools` / `model`) of each file prefixed `aki-` — these are the installed Aki agent definitions. The directory is shared with the user's own agents, so introduce only the `aki-` ones. If the directory does not exist, that layer is simply not installed: drop the section rather than describing it.
 4. Render a compact overview with these sections:
 
    - **Skills (active, user-invoked)** — one row per aki-skill: its `/name`, its one-line description (from frontmatter), and when to reach for it.
    - **Agent definitions (who the work gets handed to)** — one row per installed `aki-` agent from step 3: what it is for, and the property that is mechanical rather than promised (its `tools:` list, which is what makes a read-only agent actually read-only, and its `model:`, so a tier is never improvised). Say the thing people get wrong: this is a catalog, not a roster — an agent is spawned because a specific requirement needs it, never because it exists.
-   - **Passive system (akirule)** — explain the load mechanisms: core rules and the router always loaded (`@`-imported by `CLAUDE.md`); contextual/analytical rules read when the task's domain matches a route — by meaning, never keywords; full load when the owner asks for the whole corpus. `akirule` is hidden from the `/` menu by design (`user-invocable: false`) — it is imported, not a command.
+   - **Passive system (akirule)** — explain the load mechanisms: the behavior floor and the router always loaded (`@`-imported by `CLAUDE.md`); every other rule read when the task's domain matches a route — by meaning, never keywords — and, on Claude Code, enforced for artifact routes by the `aki-route-guard` hook (the first edit of a code file, `.md`, `CHANGELOG.md`, `.vue`, `.rs`, `.sql` … is denied until its rule was read); full load when the owner asks for the whole corpus. `akirule` is hidden from the `/` menu by design (`user-invocable: false`) — it is imported, not a command.
    - **One brain, three modes** — `METHOD-deep-think.md` is read passively by the router inside normal tasks (brief, inline, at most one clarifying question), as a triggered self-run when an `agent.A3` trigger holds or `/akithink` self-runs on a genuine decision (non-interactive, depth scaled to difficulty, ends in decide-and-report or escalation), and interactively by `/akithink` when the owner asks for a session. Short version of the comparison, not the full METHOD text.
    - **Editing rules** — this whole system is generated from a source repo (akidevrule); the installed copies under `~/.aki/akidevrule` and `~/.claude` are deployed output, never edited directly. Changes go through the source repo + `install.sh`. Note for context: the same skill corpus (not the rule corpus) is also synced by `install.sh` to Antigravity/Gemini and to Codex, Kiro, and Grok CLIs on this machine if present — this skill itself only introduces the Claude Code side.
 
@@ -42,6 +42,6 @@ Invoke with `/akihelp`, or whenever the user asks, in any wording, what this set
    | An analysis in chat is too dense to read as text | `/akihtmlreport` | Renders the analysis already in the conversation as one self-contained HTML file — it visualizes, it does not re-analyze |
    | Unsure whether a rule loaded at all | Read the `[RULES]` line, or ask to load the whole corpus | Every response carries a `[RULES]` receipt naming every rule file in context, so "the rule never arrived" (absent from the line) is visibly different from "the rule arrived and was ignored" — the two have opposite fixes. A full-load request reads everything |
 
-6. Close with the one caveat that changes how people use all of the above: **the router is guaranteed, a routed file is not** — `index.md`, the three core rule files and the router are `@`-imported through `CLAUDE.md`, but a contextual file enters context only when the model `Read`s it on a route match. When something must be deterministic, name the file in the prompt (*"Read `~/.aki/akidevrule/RULE-ui-pattern.md`, then …"*) instead of trusting the signal to fire.
+6. Close with the one caveat that changes how people use all of the above: **the router is guaranteed, a routed file is not** — `RULE-agent-behavior.md` and the router are `@`-imported through `CLAUDE.md`; a routed file enters context when the model `Read`s it — enforced by the route-gate hook when the task edits a matching artifact, best-effort on meaning-only routes. When something on a meaning-only route must be deterministic, name the file in the prompt (*"Read `~/.aki/akidevrule/RULE-ui-pattern.md`, then …"*) instead of trusting the signal to fire.
 
 7. Keep the output scannable: compact tables or short bulleted sections, not an essay. Respond in the user's language, and translate the example prompts into that language rather than pasting them verbatim in English.

package/skills/akiopen/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: akiopen
+description: Session-opening brief — what is still pending in this project, and nothing else. Use whenever a session opens on a project or the owner asks, in any wording, what is unfinished, what the active plans or notes say, what an inbox file still lists, or what to pick up next. Read-only; reports only what needs doing, in a fixed four-field shape, ranked by severity.
+user-invocable: true
+---
+
+# akiopen — what is pending here
+
+Opening a project means rebuilding the picture of unfinished work from five places nobody should have to remember (`ux.A2`). This skill reads all five in one pass and reports only what still needs doing. It is an audit (`agent.B5`): no file edits, no git mutation, no note or plan marked done.
+
+## Scan — one batched pass, only surfaces that exist
+
+```bash
+git status --short && git diff --stat | tail -1
+python3 ~/.claude/skills/akidevsync-notes/scripts/notes_cli.py .akidevsync/notes.json list --pending --detail
+grep -c '^\s*- \[ \]' docs/plan/*.md docs/*.md /dev/null 2>/dev/null | grep -v ':0$'
+awk '/^## \[Unreleased\]/{f=1;next} /^## \[/{f=0} f' CHANGELOG.md | grep -c '^- '
+grep -rn -i 'needs owner\|needs mac\|manual test\|unverified' docs/plan/*.md 2>/dev/null
+```
+
+| Surface | Pending means |
+|---|---|
+| Working tree | modified or untracked files; group them by directory, not one line per file |
+| Notes | `.akidevsync/notes.json` tasks with `done: false`; pinned first |
+| Active plans | `docs/plan/*.md` outside `done/` with open `- [ ]` items, or a plan whose text says done but still sits outside `done/` (`docs.B1`) |
+| Inbox files | any top-level `docs/*.md` with open `- [ ]` items — tasks pushed in from an upstream standard or another repo |
+| Release | `[Unreleased]` has entries, or the tree changed with no entry yet (`release.A`) |
+| Hand-offs | a line in an active plan waiting on the owner or another machine (`coding.B3`) |
+
+A surface the project does not have is skipped silently. A project `CLAUDE.md` may name additional inbox or plan paths; read it before scanning.
+
+## Report — pending only, never an inventory
+
+- One item per pending thing, at most seven, ranked by severity (`ux.C1`); the rest collapse into one count line.
+- Each item carries four fields: **problem** (what is pending, `path:line`) · **why it is still open** (from the plan text, note age, git dates — measured, never guessed; write *unclear* when the sources do not say) · **proposal** (one sentence) · **goal** (what closes it).
+- Nothing pending: one line, nothing else.
+- Half-finished work that cannot be told from an abandoned experiment is reported as unclassified and asked about, never sorted by guess (`agent.B5`).
+- The report is the deliverable. Fixing anything, including moving a finished plan to `done/`, is a separate request.