@maccesar/aiskills 1.17.0 → 1.18.0

package/skills/session-log/references/file-layout.md

@@ -1,7 +1,6 @@
 # The four files
 
-Read this when installing the convention in a project or migrating one that keeps
-its notes somewhere else.
+Read this when installing the convention in a project or migrating one that keeps its notes somewhere else.
 
 <!-- TOC-START -->
 ## Contents
@@ -36,8 +35,7 @@ Same names in every project. That's what makes them findable without asking.
 
 ## The pointer block
 
-Identical in every context file. Keep it this short — duplicated prose drifts,
-three lines don't.
+Identical in every context file. Keep it this short — duplicated prose drifts, three lines don't.
 
 ```markdown
 ## Project state
@@ -59,15 +57,13 @@ Where the tool supports imports, import the three stable files:
 @docs/project/decisions.md
 ```
 
-Never `@docs/project/status.md`. That single line is the difference between a
-cache that survives and one that gets thrown away on every update.
+Never `@docs/project/status.md`. That single line is the difference between a cache that survives and one that gets thrown away on every update.
 
 ## Two variants
 
 ### One repo, several packages
 
-A monorepo takes the opposite answer from two sibling repos: **one `docs/project/`
-at the root**, with a heading per package.
+A monorepo takes the opposite answer from two sibling repos: **one `docs/project/` at the root**, with a heading per package.
 
 ```
 docs/project/
@@ -75,19 +71,13 @@ docs/project/
   requirements.md  same headings
 ```
 
-Sibling repos get their own files because each has its own branch, its own deploy
-state and its own history — three things that go stale independently. A monorepo has
-one of each. Splitting the notes per package there would invent a boundary git
-doesn't have, and the cross-package work — the half that actually goes wrong, the
-API change that breaks the web build — would have no obvious home.
+Sibling repos get their own files because each has its own branch, its own deploy state and its own history — three things that go stale independently. A monorepo has one of each. Splitting the notes per package there would invent a boundary git doesn't have, and the cross-package work — the half that actually goes wrong, the API change that breaks the web build — would have no obvious home.
 
 The vocabulary rule is unchanged: `apps/api` is a heading, not a directory of notes.
 
 ### More than one person writing
 
-`status.md` is rewritten whole, by whoever is working, every session. Two people or
-two live branches means merge conflicts in it, reliably. That's a fact to plan for
-rather than a flaw to design around, because both obvious fixes are worse:
+`status.md` is rewritten whole, by whoever is working, every session. Two people or two live branches means merge conflicts in it, reliably. That's a fact to plan for rather than a flaw to design around, because both obvious fixes are worse:
 
 | Tempting fix | What it costs |
 | --- | --- |
@@ -95,52 +85,30 @@ rather than a flaw to design around, because both obvious fixes are worse:
 | `.gitignore` it | The notes never reach the person they were written for |
 | Only the lead updates it | It goes stale the first week the lead is busy |
 
-Resolve conflicts by **keeping both sides and merging by section** — two people's
-"In flight" entries are both true, and whichever loses a conflict is information
-nobody gets back. If the friction is constant rather than occasional, the team wants
-a heading per workstream inside the file. Still one file.
+Resolve conflicts by **keeping both sides and merging by section** — two people's "In flight" entries are both true, and whichever loses a conflict is information nobody gets back. If the friction is constant rather than occasional, the team wants a heading per workstream inside the file. Still one file.
 
 ## Repos that come in pairs
 
-A web backend and the mobile client that consumes it. The mechanics of installing
-and closing both are in the skill; what follows is the detail that didn't need to
-load every session.
+A web backend and the mobile client that consumes it. The mechanics of installing and closing both are in the skill; what follows is the detail that didn't need to load every session.
 
-**Install from inside each repo, separately.** Open the backend, install; open the
-app, install. It's a one-time act per repo and it's worth doing from the right
-place: sitting inside the project means its own context file loads, its own MCP
-servers connect, and its stack-specific skills detect themselves. Installing a
-repo's notes from its sibling means describing a project you're looking at from
-outside — and the result reads like it, because the detail that makes `context.md`
-useful is exactly what you don't see from across the fence.
+**Install from inside each repo, separately.** Open the backend, install; open the app, install. It's a one-time act per repo and it's worth doing from the right place: sitting inside the project means its own context file loads, its own MCP servers connect, and its stack-specific skills detect themselves. Installing a repo's notes from its sibling means describing a project you're looking at from outside — and the result reads like it, because the detail that makes `context.md` useful is exactly what you don't see from across the fence.
 
-Put the sibling's **path** in the header of `status.md`, not just its name, so
-whoever reads it next can actually go there:
+Put the sibling's **path** in the header of `status.md`, not just its name, so whoever reads it next can actually go there:
 
 ```markdown
 **Sibling:** `../../Apps/EM Industrial` (Titanium client) — waiting on
 `/work-orders/{id}/progress`, not built here yet.
 ```
 
-**Once both are installed, updating them from one session is fine** — that's the
-day-to-day case, and it's different from installing. The files already exist and
-carry the project's own vocabulary; you're appending what changed, not inventing a
-description of a repo you can't see.
+**Once both are installed, updating them from one session is fine** — that's the day-to-day case, and it's different from installing. The files already exist and carry the project's own vocabulary; you're appending what changed, not inventing a description of a repo you can't see.
 
-Write the sibling's status from what you did to it, not from what you assume about
-it. "Added the client call for `/work-orders/{id}/progress`" is something you know.
-"The app is now feature-complete for E5" is something the app would have to tell
-you. And if the sibling isn't reachable from where you're working, say so in the
-handoff rather than guessing: "endpoint added here; the app side needs its status
-updated, I couldn't reach that repo" is honest and actionable. A confident claim
-about a repo you didn't open is neither.
+Write the sibling's status from what you did to it, not from what you assume about it. "Added the client call for `/work-orders/{id}/progress`" is something you know. "The app is now feature-complete for E5" is something the app would have to tell you. And if the sibling isn't reachable from where you're working, say so in the handoff rather than guessing: "endpoint added here; the app side needs its status updated, I couldn't reach that repo" is honest and actionable. A confident claim about a repo you didn't open is neither.
 
 ## Templates
 
 ### `docs/project/status.md`
 
-The only file that changes every session. Keep it short enough that someone
-actually reads it.
+The only file that changes every session. Keep it short enough that someone actually reads it.
 
 ```markdown
 # Status — <YYYY-MM-DD>
@@ -178,17 +146,11 @@ actually reads it.
 
 Absolute dates, never "yesterday" — the file outlives the session that wrote it.
 
-The three header lines exist because they're the questions asked first and
-answered worst. **Deployed is not the same as committed**: on a project that
-deploys by file sync, a change can be live and uncommitted, or committed and never
-uploaded. Write what you know and mark what you don't; a confident wrong answer
-here sends someone debugging the wrong copy of the code.
+The three header lines exist because they're the questions asked first and answered worst. **Deployed is not the same as committed**: on a project that deploys by file sync, a change can be live and uncommitted, or committed and never uploaded. Write what you know and mark what you don't; a confident wrong answer here sends someone debugging the wrong copy of the code.
 
 ### `docs/project/requirements.md`
 
-The contract: what the system must do and how you'd know it does. Stable — it
-changes when scope changes, not when work happens. **Progress lives in
-`status.md`**, not here.
+The contract: what the system must do and how you'd know it does. Stable — it changes when scope changes, not when work happens. **Progress lives in `status.md`**, not here.
 
 ```markdown
 # Requirements
@@ -220,33 +182,19 @@ if nothing else exists>
   acceptance criterion belongs here, not in the table above.>
 ```
 
-**Invariants** are for projects where the risk isn't forgetting a feature — it's
-breaking a property while improving something else. Offline-first, no polling, a
-storage schema other code depends on, a latency budget. They read like
-conventions but they're stronger: a convention is how the team writes code, an
-invariant is a promise the system makes. Write what breaking it would look like,
-not just the rule, so it's recognizable when someone is about to do it.
+**Invariants** are for projects where the risk isn't forgetting a feature — it's breaking a property while improving something else. Offline-first, no polling, a storage schema other code depends on, a latency budget. They read like conventions but they're stronger: a convention is how the team writes code, an invariant is a promise the system makes. Write what breaking it would look like, not just the rule, so it's recognizable when someone is about to do it.
 
-Not every project has them. Skip the section when the honest answer is that
-nothing here is that load-bearing.
+Not every project has them. Skip the section when the honest answer is that nothing here is that load-bearing.
 
-**When the requirements live in another repo**, this file is an index pointing
-outward rather than a self-contained contract — half its rows may reference
-`../other-repo/…`. That's correct: copying the spec across creates a second copy
-that drifts. Say plainly at the top which repo owns the contract.
+**When the requirements live in another repo**, this file is an index pointing outward rather than a self-contained contract — half its rows may reference `../other-repo/…`. That's correct: copying the spec across creates a second copy that drifts. Say plainly at the top which repo owns the contract.
 
-Write acceptance criteria you could hand to someone else to check. "Payments
-work" is not one; "charging a member writes a Payment row and the receipt shows
-the folio" is. If you can't write one, the requirement isn't specified — say so
-in **Unspecified** rather than pretending the table is complete.
+Write acceptance criteria you could hand to someone else to check. "Payments work" is not one; "charging a member writes a Payment row and the receipt shows the folio" is. If you can't write one, the requirement isn't specified — say so in **Unspecified** rather than pretending the table is complete.
 
-The **Out of scope** section earns its place on client work: it's the cheapest
-insurance against a disagreement six weeks later about what was included.
+The **Out of scope** section earns its place on client work: it's the cheapest insurance against a disagreement six weeks later about what was included.
 
 ### `docs/project/decisions.md`
 
-Append-only. Old entries stay even when superseded; a decision that was reversed
-is more informative than one that was deleted.
+Append-only. Old entries stay even when superseded; a decision that was reversed is more informative than one that was deleted.
 
 ```markdown
 ## <YYYY-MM-DD> — <the decision in one line>
@@ -257,10 +205,7 @@ is more informative than one that was deleted.
 **Reverses:** <link to an earlier entry, when applicable>
 ```
 
-**When the date isn't knowable**, don't invent one. A repo with a single commit,
-or everything still under `[Unreleased]`, has real decisions with no traceable
-date — and stamping them with the commit date is a fabrication that later reads
-as fact. Put them in a separate section that says why:
+**When the date isn't knowable**, don't invent one. A repo with a single commit, or everything still under `[Unreleased]`, has real decisions with no traceable date — and stamping them with the commit date is a fabrication that later reads as fact. Put them in a separate section that says why:
 
 ```markdown
 ## Decisions without a traceable date
@@ -272,13 +217,9 @@ reasoning is recovered from the code and the docs; the dates are not known.
 **Chose / Over / Because:** <as above>
 ```
 
-These are usually the most valuable entries in the file, because they're the ones
-that explain why the code doesn't match the spec. Losing them to keep the template
-tidy is the wrong trade.
+These are usually the most valuable entries in the file, because they're the ones that explain why the code doesn't match the spec. Losing them to keep the template tidy is the wrong trade.
 
-**Archiving.** Append-only and imported-at-startup is a combination with a shelf
-life: every session pays for the whole file, and most of what it's paying for is a
-decision from two years ago that nobody is about to revisit.
+**Archiving.** Append-only and imported-at-startup is a combination with a shelf life: every session pays for the whole file, and most of what it's paying for is a decision from two years ago that nobody is about to revisit.
 
 Past roughly two hundred lines, split it:
 
@@ -287,23 +228,15 @@ docs/project/decisions.md          current year — imported
 docs/project/decisions-archive.md  everything older — NOT imported
 ```
 
-Move entries oldest-first, keep them verbatim, and leave a line at the top of
-`decisions.md` saying where the rest went. Then check the import chain again — the
-archive must not be pulled in by any `@` line, or the split bought nothing.
+Move entries oldest-first, keep them verbatim, and leave a line at the top of `decisions.md` saying where the rest went. Then check the import chain again — the archive must not be pulled in by any `@` line, or the split bought nothing.
 
-Two rules keep the archive honest. A superseded entry stays with its reverser, even
-if that means keeping an old entry in the current file — a reversal that outlives
-the decision it reversed reads as if the original never happened. And an entry the
-project still argues about is current by definition, whatever its date.
+Two rules keep the archive honest. A superseded entry stays with its reverser, even if that means keeping an old entry in the current file — a reversal that outlives the decision it reversed reads as if the original never happened. And an entry the project still argues about is current by definition, whatever its date.
 
-Two hundred lines is a prompt to look, not a threshold to enforce. A project with
-twelve decisions in four years never needs this.
+Two hundred lines is a prompt to look, not a threshold to enforce. A project with twelve decisions in four years never needs this.
 
 ### `docs/project/context.md`
 
-How the project is put together, and what a newcomer would get wrong on day one.
-Anything derivable from reading the code doesn't belong here — this is for what
-the code *doesn't* say.
+How the project is put together, and what a newcomer would get wrong on day one. Anything derivable from reading the code doesn't belong here — this is for what the code *doesn't* say.
 
 ```markdown
 # Context
@@ -323,62 +256,31 @@ the code *doesn't* say.
 - <The thing that cost someone a day, and how to avoid it.>
 ```
 
-The map goes first because it's what someone new needs first: knowing what exists
-saves them from rewriting it. List every document you found, including the ones
-that turned out to be stale — marked as stale. A document omitted from the map is
-a document nobody will open again.
+The map goes first because it's what someone new needs first: knowing what exists saves them from rewriting it. List every document you found, including the ones that turned out to be stale — marked as stale. A document omitted from the map is a document nobody will open again.
 
 ## Migrating an existing project
 
-Projects that already keep notes somewhere — `.claude/memory/`, a roadmap under
-`docs/`, a planning doc — get migrated rather than duplicated. Two locations is
-the problem this convention exists to solve.
+Projects that already keep notes somewhere — `.claude/memory/`, a roadmap under `docs/`, a planning doc — get migrated rather than duplicated. Two locations is the problem this convention exists to solve.
 
-1. **Read what's there** and sort it: is this line status, a decision, or context?
-   Most existing notes are a mix, and that's exactly why they're hard to use.
-2. **Split it into the four files.** Status goes to `status.md` even if it was
-   living in an imported file — especially then.
-3. **Delete the old location** and update anything that referenced it, including
-   `@import` lines in context files.
+1. **Read what's there** and sort it: is this line status, a decision, or context? Most existing notes are a mix, and that's exactly why they're hard to use.
+2. **Split it into the four files.** Status goes to `status.md` even if it was living in an imported file — especially then.
+3. **Delete the old location** and update anything that referenced it, including `@import` lines in context files.
 4. **Add the pointer block** to every context file.
-5. **Tell the person what moved where**, concretely. They need to be able to check
-   that nothing was lost, and a migration they can't audit is one they won't trust.
+5. **Tell the person what moved where**, concretely. They need to be able to check that nothing was lost, and a migration they can't audit is one they won't trust.
 
-If the project has a planning doc with real structure — a numbered checklist, a
-PRD — don't flatten it into `status.md`. Leave it where it is and reference it
-from `status.md`. The convention is about knowing where to look, not about
-destroying work that already has a shape.
+If the project has a planning doc with real structure — a numbered checklist, a PRD — don't flatten it into `status.md`. Leave it where it is and reference it from `status.md`. The convention is about knowing where to look, not about destroying work that already has a shape.
 
 ### Upgrading an earlier version of this convention
 
-Repos installed before the four-file layout settled look almost right and aren't:
-a lone `docs/status/current.md`, a `docs/project/` holding three files named by
-hand, an `estado-actual.md` next to a `decisiones.md`. This is an upgrade, not a
-migration, and the difference matters — the content was written by someone who was
-there, so it's correct until the repo contradicts it.
-
-1. **`git mv` into the fixed names**, so the history follows the file. Copying and
-   deleting loses the one thing that made the old file trustworthy.
-2. **Split by volatility, not by topic.** The usual finding is a single file mixing
-   a stable architecture description with three lines of "where I left off". The
-   stable half goes to `context.md` or `requirements.md`; only the volatile half
-   ends up in `status.md`.
-3. **Update every pointer**, including `@import` lines and any reference from
-   `README.md` or a sibling repo's header. A pointer to the old path is worse than
-   no pointer: it resolves to nothing and looks maintained.
-4. **Say what moved where**, path by path. An upgrade someone can't audit is one
-   they won't trust, and this one moves files they wrote.
+Repos installed before the four-file layout settled look almost right and aren't: a lone `docs/status/current.md`, a `docs/project/` holding three files named by hand, an `estado-actual.md` next to a `decisiones.md`. This is an upgrade, not a migration, and the difference matters — the content was written by someone who was there, so it's correct until the repo contradicts it.
+
+1. **`git mv` into the fixed names**, so the history follows the file. Copying and deleting loses the one thing that made the old file trustworthy.
+2. **Split by volatility, not by topic.** The usual finding is a single file mixing a stable architecture description with three lines of "where I left off". The stable half goes to `context.md` or `requirements.md`; only the volatile half ends up in `status.md`.
+3. **Update every pointer**, including `@import` lines and any reference from `README.md` or a sibling repo's header. A pointer to the old path is worse than no pointer: it resolves to nothing and looks maintained.
+4. **Say what moved where**, path by path. An upgrade someone can't audit is one they won't trust, and this one moves files they wrote.
 
 ## Sizing
 
-A repo with one commit doesn't need four files with nothing in them. Start with
-whichever ones have content — often `requirements.md` and `status.md` early on,
-`context.md` and `decisions.md` once the thing exists — and add the rest when
-there's something real to put in them. A `decisions.md` whose only entry is the decision to keep decisions is a
-file that exists to look organized.
-
-**The pointer block lists the files that exist.** Listing all four from the start is
-tempting — it shows the shape — but three of the four lines then point at nothing,
-and a pointer that resolves to a missing file trains the next reader to distrust the
-block. Add the line when the file arrives; it's one line, at the moment it becomes
-true.
+A repo with one commit doesn't need four files with nothing in them. Start with whichever ones have content — often `requirements.md` and `status.md` early on, `context.md` and `decisions.md` once the thing exists — and add the rest when there's something real to put in them. A `decisions.md` whose only entry is the decision to keep decisions is a file that exists to look organized.
+
+**The pointer block lists the files that exist.** Listing all four from the start is tempting — it shows the shape — but three of the four lines then point at nothing, and a pointer that resolves to a missing file trains the next reader to distrust the block. Add the line when the file arrives; it's one line, at the moment it becomes true.

package/skills/session-log/references/verification.md

@@ -1,12 +1,10 @@
 # Verifying that work actually exists
 
-Read this before marking anything as done. The goal is narrow: turn "I finished
-X" into "I found the artifacts X would have produced."
+Read this before marking anything as done. The goal is narrow: turn "I finished X" into "I found the artifacts X would have produced."
 
 ## What "done" is allowed to mean
 
-Be careful with the word — these are different claims, and a record that collapses
-them into one checkmark loses the distinction exactly when someone needs it:
+Be careful with the word — these are different claims, and a record that collapses them into one checkmark loses the distinction exactly when someone needs it:
 
 | Claim | What it means |
 | --- | --- |
@@ -15,39 +13,24 @@ them into one checkmark loses the distinction exactly when someone needs it:
 | Reviewed | A human looked at it |
 | Shipped | It's deployed or released |
 
-Use the distinction to be *more* precise, not to avoid answering. "Implemented,
-not yet verified — no test covers it" is a useful record. Marking nothing at all
-because verification was impossible is not.
+Use the distinction to be *more* precise, not to avoid answering. "Implemented, not yet verified — no test covers it" is a useful record. Marking nothing at all because verification was impossible is not.
 
 ## Three ways records go bad
 
-**Percentages the repo can't support.** A percentage needs a fixed denominator —
-a checklist with a known number of items. Without one, any number is invented.
-Count what's enumerable or describe status in words.
+**Percentages the repo can't support.** A percentage needs a fixed denominator — a checklist with a known number of items. Without one, any number is invented. Count what's enumerable or describe status in words.
 
-**Duplicating what the repo already records.** Git history, the CHANGELOG and the
-code are better sources than a note paraphrasing them. Record what they *can't*
-say: why an approach was abandoned, what failed, what looks wrong but is deliberate.
+**Duplicating what the repo already records.** Git history, the CHANGELOG and the code are better sources than a note paraphrasing them. Record what they *can't* say: why an approach was abandoned, what failed, what looks wrong but is deliberate.
 
-**Padding.** A handoff nobody reads is a handoff that failed. Three specific lines
-beat a page of headers. Length is not thoroughness.
+**Padding.** A handoff nobody reads is a handoff that failed. Three specific lines beat a page of headers. Length is not thoroughness.
 
 ## The method
 
-Someone's claim is about behavior. The repo holds artifacts. Verification is
-translating between the two:
-
-1. **Name the artifacts before searching.** "Finished the payments module" should
-   produce a concrete list first — a service class, a route, a migration, a test.
-   Writing that list before you look is what stops you from accepting whatever
-   you happen to find as sufficient.
-2. **Search for those specific things**, not for the feature name. Grepping for
-   "payment" finds comments, TODOs, and unrelated strings. Grepping for the route
-   registration or the class definition finds the thing itself.
-3. **Distinguish existence from completeness.** A file that exists but contains a
-   stub is not the feature. Open what you find when the claim is substantial.
-4. **Report the gap, not just the verdict.** "Found the service and the routes;
-   no tests and no migration" is useful. "Not done" is not.
+Someone's claim is about behavior. The repo holds artifacts. Verification is translating between the two:
+
+1. **Name the artifacts before searching.** "Finished the payments module" should produce a concrete list first — a service class, a route, a migration, a test. Writing that list before you look is what stops you from accepting whatever you happen to find as sufficient.
+2. **Search for those specific things**, not for the feature name. Grepping for "payment" finds comments, TODOs, and unrelated strings. Grepping for the route registration or the class definition finds the thing itself.
+3. **Distinguish existence from completeness.** A file that exists but contains a stub is not the feature. Open what you find when the claim is substantial.
+4. **Report the gap, not just the verdict.** "Found the service and the routes; no tests and no migration" is useful. "Not done" is not.
 
 ## What to search for, by stack
 
@@ -80,8 +63,7 @@ A Livewire feature that has a class but no Blade view is not done. Check both.
 | Native module | Declared in `tiapp.xml` under `<modules>` **and** present in `modules/` |
 | Platform config | `tiapp.xml` |
 
-A controller without its view compiles to nothing usable. A string added to one
-locale and not the others ships as a raw key in the missing language.
+A controller without its view compiles to nothing usable. A string added to one locale and not the others ships as a raw key in the missing language.
 
 ### Node / TypeScript
 
@@ -124,27 +106,17 @@ locale and not the others ships as a raw key in the missing language.
 
 ## Claims in a status file you didn't write
 
-Resuming work means reading claims written weeks ago by someone — possibly you —
-who is no longer available to ask. The method above applies unchanged, with one
-addition: an old record has a **direction of error**. It says what was true when it
-was written, so its claims rot toward being *understated* about what exists and
-*overstated* about what's blocked.
+Resuming work means reading claims written weeks ago by someone — possibly you — who is no longer available to ask. The method above applies unchanged, with one addition: an old record has a **direction of error**. It says what was true when it was written, so its claims rot toward being *understated* about what exists and *overstated* about what's blocked.
 
-- "Not started" from three weeks ago may well be finished. Check the artifacts
-  before repeating it — this is the most common way a resumed session redoes work.
-- "Blocked on the client" has a date attached to a person who has probably answered
-  since. Flag it as needing a human check rather than carrying it forward as fact.
-- "Next step: X" may be stale in a way the file cannot know. If X is already in the
-  code, say so instead of proposing it again.
+- "Not started" from three weeks ago may well be finished. Check the artifacts before repeating it — this is the most common way a resumed session redoes work.
+- "Blocked on the client" has a date attached to a person who has probably answered since. Flag it as needing a human check rather than carrying it forward as fact.
+- "Next step: X" may be stale in a way the file cannot know. If X is already in the code, say so instead of proposing it again.
 
-The safe form is attribution: "the file says the payments module was left half-done
-on 2026-07-14; the routes and the service exist now, so part of that landed after it
-was written". That gives the person both the record and the correction.
+The safe form is attribution: "the file says the payments module was left half-done on 2026-07-14; the routes and the service exist now, so part of that landed after it was written". That gives the person both the record and the correction.
 
 ## Claims that can't be verified from the repo
 
-Some are legitimate and simply live elsewhere: work in another repository, a
-deploy, a conversation with a client, a design decision.
+Some are legitimate and simply live elsewhere: work in another repository, a deploy, a conversation with a client, a design decision.
 
 Record them. Label them. The pattern that keeps the log trustworthy is:
 
@@ -158,16 +130,10 @@ The distinction costs one word and preserves the whole point of the record.
 
 ## Deployment is not git state
 
-A change can be live on a server without being committed, and committed without
-being live. Repos with file-sync deployment (SFTP-on-save watchers, rsync hooks)
-break the assumption that git reflects production entirely.
+A change can be live on a server without being committed, and committed without being live. Repos with file-sync deployment (SFTP-on-save watchers, rsync hooks) break the assumption that git reflects production entirely.
 
-Never infer deployment state from git. When it matters, check the deployment
-configuration in the repo, or ask.
+Never infer deployment state from git. When it matters, check the deployment configuration in the repo, or ask.
 
 ## Tests: the output is the evidence
 
-"Tests pass" is a claim like any other. If you ran them, quote the count and the
-result. If you didn't, say so. A log that records passing tests nobody ran is
-worse than one that records nothing, because it stops the next session from
-running them.
+"Tests pass" is a claim like any other. If you ran them, quote the count and the result. If you didn't, say so. A log that records passing tests nobody ran is worse than one that records nothing, because it stops the next session from running them.

package/skills/stitch-showcase/references/12-video-embedding.md

@@ -2,16 +2,11 @@
 
 ## Purpose
 
-Sometimes a Stitch slot needs to show a video instead of a still image
-(product demo, animated logo, looping background, recorded screen). This
-document captures the exact pattern that works across browsers and avoids
-the common pitfalls — content recropping, layout shift, AV1 codec, and
-aspect-ratio mismatch with the original wrapper.
+Sometimes a Stitch slot needs to show a video instead of a still image (product demo, animated logo, looping background, recorded screen). This document captures the exact pattern that works across browsers and avoids the common pitfalls — content recropping, layout shift, AV1 codec, and aspect-ratio mismatch with the original wrapper.
 
 ## The Tag
 
-Use a plain `<video>` element with native `width` and `height` attributes
-plus inline styling for safe defaults:
+Use a plain `<video>` element with native `width` and `height` attributes plus inline styling for safe defaults:
 
 ```html
 <video
@@ -27,8 +22,7 @@ plus inline styling for safe defaults:
 </video>
 ```
 
-Replace `W` / `H` with the **native** video dimensions and `<slug>` with
-the screen slug (or whatever filename you used inside `videos/`).
+Replace `W` / `H` with the **native** video dimensions and `<slug>` with the screen slug (or whatever filename you used inside `videos/`).
 
 ### Why each attribute
 
@@ -43,15 +37,13 @@ the screen slug (or whatever filename you used inside `videos/`).
 
 ## File Workflow
 
-1. **Download** the source video. For Facebook/Instagram/YouTube/TikTok we
-   recommend `yt-dlp`:
+1. **Download** the source video. For Facebook/Instagram/YouTube/TikTok we recommend `yt-dlp`:
 
    ```bash
    yt-dlp "https://www.facebook.com/<...>/videos/<id>" -o "videos/<slug>.%(ext)s"
    ```
 
-2. **Re-encode to H.264** if the source comes down as AV1. AV1 doesn't
-   preview in macOS Finder and is rejected by Safari < 17:
+2. **Re-encode to H.264** if the source comes down as AV1. AV1 doesn't preview in macOS Finder and is rejected by Safari < 17:
 
    ```bash
    ffmpeg -i in.mp4 \
@@ -63,12 +55,9 @@ the screen slug (or whatever filename you used inside `videos/`).
 
    - `-preset fast`: balanced speed/quality.
    - `-crf 23`: visually-lossless default; lower number = bigger file.
-   - `-movflags +faststart`: moves the moov atom to the front so the video
-     can start playing before fully downloaded.
+   - `-movflags +faststart`: moves the moov atom to the front so the video can start playing before fully downloaded.
 
-3. **Place** the encoded `.mp4` in a `videos/` folder at the **project
-   level** (the same level as `stitch/` or `showcase/`, not inside
-   `assets/`), so the build keeps it out of the screen-extraction pipeline:
+3. **Place** the encoded `.mp4` in a `videos/` folder at the **project level** (the same level as `stitch/` or `showcase/`, not inside `assets/`), so the build keeps it out of the screen-extraction pipeline:
 
    ```text
    my-project/
@@ -80,8 +69,7 @@ the screen slug (or whatever filename you used inside `videos/`).
            └── <slug>.html     ← references ../../videos/hero.mp4
    ```
 
-4. **Reference from the screen HTML** with a relative path. From inside
-   `showcase/assets/<slug>.html`, `videos/` is two levels up:
+4. **Reference from the screen HTML** with a relative path. From inside `showcase/assets/<slug>.html`, `videos/` is two levels up:
 
    ```html
    <source src="../../videos/hero.mp4" type="video/mp4">
@@ -89,18 +77,14 @@ the screen slug (or whatever filename you used inside `videos/`).
 
 ## Aspect-Ratio Mismatch
 
-The original Stitch wrapper for a video slot usually carries a fixed
-aspect ratio (e.g. `aspect-[4/5]`). If your video is a different shape —
-say 9/16 — keeping the wrapper's aspect locks the video into the wrong
-box, which then forces a choice:
+The original Stitch wrapper for a video slot usually carries a fixed aspect ratio (e.g. `aspect-[4/5]`). If your video is a different shape — say 9/16 — keeping the wrapper's aspect locks the video into the wrong box, which then forces a choice:
 
 | Option | Effect |
 |--------|--------|
 | Keep wrapper's `aspect-*` + `object-cover` | Video crops; logos and edges get chopped. |
 | **Remove wrapper's `aspect-*` + `height:auto`** | Video keeps its native aspect; the slot grows or shrinks vertically to fit. ✅ |
 
-The second option is almost always what you want — better to have a
-slightly taller card than to chop the brand logo out of the frame.
+The second option is almost always what you want — better to have a slightly taller card than to chop the brand logo out of the frame.
 
 ## Quick Sanity Checks
 
@@ -109,5 +93,4 @@ After embedding, open the screen in a browser and confirm:
 - The video autoplays without a tap on Chrome, Safari, and Firefox.
 - The video loops cleanly (no flash on rewind).
 - On mobile (iOS Safari), it autoplays silently inline (not fullscreen).
-- The file size is reasonable — re-encode with a higher `-crf` if it's
-  more than ~3-5 MB per 10 seconds.
+- The file size is reasonable — re-encode with a higher `-crf` if it's more than ~3-5 MB per 10 seconds.

package/skills/stitch-showcase/references/13-language-detection.md

@@ -2,19 +2,13 @@
 
 ## Purpose
 
-The `<html lang="…">` attribute on the generated `index.html` and
-`viewer.html` tells the browser which natural language the content uses.
-If the value disagrees with the actual content, Chrome shows a "Translate
-this page" banner and assistive technologies pronounce words with the
-wrong phoneme set. This document explains how the build picks the value
-and how to override it.
+The `<html lang="…">` attribute on the generated `index.html` and `viewer.html` tells the browser which natural language the content uses. If the value disagrees with the actual content, Chrome shows a "Translate this page" banner and assistive technologies pronounce words with the wrong phoneme set. This document explains how the build picks the value and how to override it.
 
 ## Resolution Order
 
 The `lang` attribute is chosen by the first rule that fires:
 
-1. **CLI flag** (future — not implemented yet): `--lang es` on
-   `build_showcase.py`.
+1. **CLI flag** (future — not implemented yet): `--lang es` on `build_showcase.py`.
 2. **`showcase.json` field**:
 
    ```json
@@ -33,50 +27,31 @@ The `lang` attribute is chosen by the first rule that fires:
    es
    ```
 
-4. **Auto-detection** from the text content of `DESIGN.md` (project name,
-   section names, descriptions). The detector counts Spanish signals:
+4. **Auto-detection** from the text content of `DESIGN.md` (project name, section names, descriptions). The detector counts Spanish signals:
 
    - Accented characters (`á é í ó ú ñ`).
-   - Common Spanish stop words (`de`, `el`, `la`, `los`, `las`, `para`,
-     `con`, `pantalla`, `aplicación`, `usuario`, etc.).
+   - Common Spanish stop words (`de`, `el`, `la`, `los`, `las`, `para`, `con`, `pantalla`, `aplicación`, `usuario`, etc.).
 
-   If the Spanish score crosses a small threshold, the lang resolves to
-   `"es"`; otherwise it falls through.
+   If the Spanish score crosses a small threshold, the lang resolves to `"es"`; otherwise it falls through.
 
 5. **Default**: `"en"`.
 
 ## When to Override
 
-The auto-detector handles obvious cases (a project whose DESIGN.md is
-entirely Spanish or entirely English), but it can be fooled by very
-short DESIGN.md files or by projects where the UI language differs from
-the documentation language. Use an explicit override when:
+The auto-detector handles obvious cases (a project whose DESIGN.md is entirely Spanish or entirely English), but it can be fooled by very short DESIGN.md files or by projects where the UI language differs from the documentation language. Use an explicit override when:
 
-- The DESIGN.md is in English but the actual screen content is Spanish
-  (you'd be documenting an es-MX app in English for a client).
+- The DESIGN.md is in English but the actual screen content is Spanish (you'd be documenting an es-MX app in English for a client).
 - The DESIGN.md is sparse and the heuristic has nothing to score on.
-- You want a non-Spanish, non-English language (`pt`, `fr`, `de` …) —
-  the auto-detector only distinguishes Spanish vs everything else.
+- You want a non-Spanish, non-English language (`pt`, `fr`, `de` …) — the auto-detector only distinguishes Spanish vs everything else.
 
 ## Why It Matters
 
-- **Chrome's translate prompt**: with `lang="en"` and Spanish content,
-  Chrome offers to translate the page to the user's locale. Users
-  perceive this as a bug.
-- **Screen readers**: VoiceOver and TalkBack switch pronunciation
-  engines per `lang`. A wrong value makes Spanish text sound like a
-  speech synthesizer trying to pronounce "configuración" as English.
-- **Search engines**: the `lang` attribute is a soft signal but it's
-  read by indexers when ranking pages by locale.
+- **Chrome's translate prompt**: with `lang="en"` and Spanish content, Chrome offers to translate the page to the user's locale. Users perceive this as a bug.
+- **Screen readers**: VoiceOver and TalkBack switch pronunciation engines per `lang`. A wrong value makes Spanish text sound like a speech synthesizer trying to pronounce "configuración" as English.
+- **Search engines**: the `lang` attribute is a soft signal but it's read by indexers when ranking pages by locale.
 
 ## Common Mistake: Mismatched Lang and Content
 
-The previous template hard-coded `lang="en"` even for Spanish-only
-projects. The fix wasn't to flip the default to `"es"` (that just moves
-the bug to English projects) — it was to detect or accept an override.
-The same logic now lives in `parse_design_md.py` (`_detect_lang`) and
-`build_showcase.py` (the `{{HTML_LANG}}` placeholder substitution).
+The previous template hard-coded `lang="en"` even for Spanish-only projects. The fix wasn't to flip the default to `"es"` (that just moves the bug to English projects) — it was to detect or accept an override. The same logic now lives in `parse_design_md.py` (`_detect_lang`) and `build_showcase.py` (the `{{HTML_LANG}}` placeholder substitution).
 
-If you ever see Chrome offering to translate one of your showcases:
-that's the signal that the resolved `lang` is wrong. Add an override to
-`showcase.json` or `DESIGN.md` and rebuild.
+If you ever see Chrome offering to translate one of your showcases: that's the signal that the resolved `lang` is wrong. Add an override to `showcase.json` or `DESIGN.md` and rebuild.