@maccesar/aiskills 1.16.1 → 1.17.1

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

@@ -1,7 +1,19 @@
 # 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
+
+- [Layout](#layout)
+- [The pointer block](#the-pointer-block)
+- [Two variants](#two-variants)
+- [Repos that come in pairs](#repos-that-come-in-pairs)
+- [Templates](#templates)
+- [Migrating an existing project](#migrating-an-existing-project)
+- [Sizing](#sizing)
+
+<!-- TOC-END -->
 
 ## Layout
 
@@ -23,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
@@ -46,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/
@@ -62,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 |
 | --- | --- |
@@ -82,17 +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.
+
+**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:
+
+```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.
+
+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>
@@ -130,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
@@ -172,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>
@@ -209,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
@@ -224,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:
 
@@ -239,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
@@ -275,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/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: stitch-showcase
-description: 'Use when the user has Google Stitch design exports and wants to do anything with them — build a gallery, organize screens, generate a navigable showcase, process zip files, or browse designs. Triggers: "organiza mis diseños de Stitch", "arma el muestrario", "organize my Stitch designs", "build the showcase", "tengo los zips de Stitch", "mis exports de Stitch", or any mention of Stitch exports, screen.png + code.html pairs, or design zip files. Also: "optimiza el showcase", "mejora las descripciones", "enrich the showcase" to improve an existing showcase.'
+description: 'Turns Google Stitch design exports (zips holding `code.html` + `screen.png`) into a navigable showcase — gallery, viewer, component catalog — in about three seconds, and enriches it on demand. Use this for anything involving those exports: "organiza mis diseños de Stitch", "arma el muestrario", "organize my Stitch designs", "build the showcase", "tengo los zips de Stitch", "mis exports de Stitch", or a bare path to a folder of design zips. Also for maintaining one that already exists: "optimiza el showcase", "mejora las descripciones", "agrega estas pantallas nuevas", "el cliente pidió otra pantalla", "estandariza los navbars", "make all the footers the same". Not for: Figma or Sketch exports, loose screenshots, redesigning the screens themselves, or building the real app from them.'
 ---
 
 # stitch-showcase
 
 Converts Google Stitch exports (zips with `code.html` + `screen.png`) into a navigable showcase with `index.html` + `viewer.html` + `catalog.html`.
 
-**Architecture**: Python script generates all HTML from pre-built templates in ~3 seconds. AI enrichment (descriptions, sections, hero text) is **optional and on-demand** — only when the user asks to optimize. The AI NEVER writes index.html or viewer.html from scratch.
+**Architecture**: a Python script generates all HTML from pre-built templates in ~3 seconds. AI enrichment (descriptions, sections, hero text) is **optional and on-demand** — only when the user asks to optimize.
 
 ## Prerequisites
 
@@ -39,7 +39,11 @@ digraph showcase {
 }
 ```
 
-**CRITICAL**: Always run `build_showcase.py` WITHOUT `--context` to generate HTMLs from templates. The `--context` flag is ONLY for debugging/inspecting the data JSON. NEVER have the AI write index.html or viewer.html manually — the templates handle layout, grid, viewer, theme, tabs, search, and all interactive features.
+Two things about this that are easy to get wrong and expensive to undo:
+
+Run `build_showcase.py` **without** `--context`, since that's the invocation that writes the HTML. `--context` only dumps the data JSON for inspection, so a run with it leaves you with no showcase and no error saying why.
+
+Don't write `index.html` or `viewer.html` by hand. The templates already carry the layout, grid, viewer, theme, tabs, search and every interactive behavior, and every build regenerates both files — so hand-written HTML costs a lot to produce and disappears on the next rebuild.
 
 ## Mode 1: Build (default — instant)
 

package/skills/stitch-showcase/references/14-troubleshooting-known-issues.md

@@ -2,39 +2,27 @@
 
 ## Purpose
 
-Working notes on issues that have shown up in real projects, the cause
-when it's understood, and the workaround. New issues should be added here
-before they show up a second time.
+Working notes on issues that have shown up in real projects, the cause when it's understood, and the workaround. New issues should be added here before they show up a second time.
 
 ---
 
 ## `catalog.html` stays on "Loading…"
 
-**Symptom**: opening `catalog.html` shows the skeleton header but the
-component grid never appears.
+**Symptom**: opening `catalog.html` shows the skeleton header but the component grid never appears.
 
-**Cause** (suspected, not yet confirmed): in projects with very dense
-HTMLs or many near-duplicate variants, `extract_catalog.py` either times
-out or returns a structure the catalog viewer chokes on.
+**Cause** (suspected, not yet confirmed): in projects with very dense HTMLs or many near-duplicate variants, `extract_catalog.py` either times out or returns a structure the catalog viewer chokes on.
 
-**Workaround**: the `index.html` template ships without the "Catalog"
-button in the header, so end users don't hit the broken page. If you
-want to inspect the catalog data, open `component_catalog.json` directly.
+**Workaround**: the `index.html` template ships without the "Catalog" button in the header, so end users don't hit the broken page. If you want to inspect the catalog data, open `component_catalog.json` directly.
 
-**Status**: open. Restore the Catalog button in
-`references/index.html` once the root cause is fixed.
+**Status**: open. Restore the Catalog button in `references/index.html` once the root cause is fixed.
 
 ---
 
 ## Chrome shows "Translate this page" banner
 
-**Symptom**: Chrome offers to translate the showcase, sometimes to a
-language that isn't even one of the two involved (Portuguese is common).
+**Symptom**: Chrome offers to translate the showcase, sometimes to a language that isn't even one of the two involved (Portuguese is common).
 
-**Cause**: the `<html lang="…">` attribute on `index.html` or
-`viewer.html` disagrees with the actual text content. See
-[`13-language-detection.md`](13-language-detection.md) for the full
-resolution order.
+**Cause**: the `<html lang="…">` attribute on `index.html` or `viewer.html` disagrees with the actual text content. See [`13-language-detection.md`](13-language-detection.md) for the full resolution order.
 
 **Workaround**: add an override.
 
@@ -59,62 +47,45 @@ Then rebuild.
 
 ## Video doesn't preview in Finder / Safari rejects it
 
-**Symptom**: a `.mp4` downloaded from Facebook / YouTube / TikTok plays
-fine in VLC and Chrome but shows a black square in macOS Finder and
-fails to play in Safari < 17.
+**Symptom**: a `.mp4` downloaded from Facebook / YouTube / TikTok plays fine in VLC and Chrome but shows a black square in macOS Finder and fails to play in Safari < 17.
 
-**Cause**: the source was encoded in AV1, which neither macOS Finder
-nor older Safari can decode.
+**Cause**: the source was encoded in AV1, which neither macOS Finder nor older Safari can decode.
 
-**Workaround**: re-encode to H.264 with ffmpeg. See
-[`12-video-embedding.md`](12-video-embedding.md) for the exact command.
+**Workaround**: re-encode to H.264 with ffmpeg. See [`12-video-embedding.md`](12-video-embedding.md) for the exact command.
 
 ---
 
 ## Skill installed both as plugin and standalone
 
-**Symptom**: after `aiskills install`, the skill folder exists at both
-`~/.claude/skills/<name>/` (from the standalone CLI) **and**
-`~/.claude/plugins/cache/<plugin>/<version>/skills/<name>/` (from the
-marketplace plugin), so changes to one path are invisible to the other.
+**Symptom**: after `aiskills install`, the skill folder exists at both `~/.claude/skills/<name>/` (from the standalone CLI) **and** `~/.claude/plugins/cache/<plugin>/<version>/skills/<name>/` (from the marketplace plugin), so changes to one path are invisible to the other.
 
-**Cause**: older versions of the `aiskills` CLI didn't detect when the
-plugin marketplace had already installed the skill and dropped a
-duplicate symlink.
+**Cause**: older versions of the `aiskills` CLI didn't detect when the plugin marketplace had already installed the skill and dropped a duplicate symlink.
 
 **Workaround**:
 
 1. Update the CLI: `npm install -g @maccesar/aiskills@latest`.
 2. Remove the standalone copy: `rm -rf ~/.claude/skills/<skill-name>`.
-3. Reinstall: `aiskills install`. The CLI now skips skills that the
-   plugin already provides.
+3. Reinstall: `aiskills install`. The CLI now skips skills that the plugin already provides.
 
 ---
 
 ## Showcase background and app background match (thumbnails disappear)
 
-**Symptom**: every card in `index.html` shows a blank rectangle because
-the screen has the same background color as the showcase canvas.
+**Symptom**: every card in `index.html` shows a blank rectangle because the screen has the same background color as the showcase canvas.
 
-**Cause**: someone reused the project's brand color as the showcase
-background instead of a neutral surface.
+**Cause**: someone reused the project's brand color as the showcase background instead of a neutral surface.
 
-**Workaround**: see `07-theme-system.md` and the Color Strategy section
-of `SKILL.md` — never use a brand color for large showcase surfaces.
+**Workaround**: see `07-theme-system.md` and the Color Strategy section of `SKILL.md` — never use a brand color for large showcase surfaces.
 
 ---
 
 ## Stitch slugs come with `_` in place of accents
 
-**Symptom**: filenames like `configuraci_n_oscuro.html` and the showcase
-displays them as "Configuraci_N Oscuro".
+**Symptom**: filenames like `configuraci_n_oscuro.html` and the showcase displays them as "Configuraci_N Oscuro".
 
 **Cause**: Google Stitch strips accented characters from filenames.
 
-**Workaround**: the build now de-mangles slugs automatically through
-`scripts/slug_demangle.py`. If a slug doesn't appear in the demangler's
-dictionary, override the title explicitly in `DESIGN.md` using the
-`Title | Description` format:
+**Workaround**: the build now de-mangles slugs automatically through `scripts/slug_demangle.py`. If a slug doesn't appear in the demangler's dictionary, override the title explicitly in `DESIGN.md` using the `Title | Description` format:
 
 ```markdown
 ### Cuenta