@maccesar/aiskills 1.16.0 → 1.17.0

package/lib/commands/doctor.js

@@ -16,6 +16,11 @@ import {
 } from '../config.js';
 import { hasHook } from '../hooks.js';
 import { readLastCheck } from '../cache.js';
+import {
+  isClaudePluginEnabled,
+  hasClaudePluginCache,
+  pluginProvidesSkill,
+} from '../claude-plugin.js';
 
 const CHECK = chalk.green('✓');
 const CROSS = chalk.red('✗');
@@ -79,8 +84,18 @@ export async function doctorCommand() {
   for (const platform of platforms) {
     const missing = [];
     const broken = [];
+    const servedByPlugin = [];
 
     for (const skill of SKILLS) {
+      // A skill the marketplace plugin provides is *supposed* to have no mirror
+      // here — the CLI removes it on purpose to avoid a duplicate entry. Counting
+      // it as missing turns a healthy marketplace install into a wall of errors
+      // telling the user to run a command that will correctly do nothing.
+      if (platform.name === 'claude' && pluginProvidesSkill(skill, homeDir)) {
+        servedByPlugin.push(skill);
+        continue;
+      }
+
       const linkPath = join(platform.skillsDir, skill);
       try {
         const stat = lstatSync(linkPath);
@@ -96,15 +111,26 @@ export async function doctorCommand() {
       }
     }
 
-    const linkedCount = SKILLS.length - missing.length - broken.length;
+    const expected = SKILLS.length - servedByPlugin.length;
+    const linkedCount = expected - missing.length - broken.length;
+    const pluginNote =
+      servedByPlugin.length > 0
+        ? chalk.dim(` (+${servedByPlugin.length} served by the marketplace plugin)`)
+        : '';
 
     if (missing.length === 0 && broken.length === 0) {
-      console.log(`    ${CHECK} ${platform.displayName}: ${SKILLS.length}/${SKILLS.length} skills linked`);
+      const summary =
+        expected === 0
+          ? `all ${servedByPlugin.length} skills served by the marketplace plugin`
+          : `${linkedCount}/${expected} skills linked${pluginNote}`;
+      console.log(`    ${CHECK} ${platform.displayName}: ${summary}`);
     } else {
       const problems = [];
       if (missing.length > 0) problems.push(`missing: ${missing.join(', ')}`);
       if (broken.length > 0) problems.push(`broken: ${broken.join(', ')}`);
-      console.log(`    ${CROSS} ${platform.displayName}: ${linkedCount}/${SKILLS.length} skills linked (${problems.join('; ')})`);
+      console.log(
+        `    ${CROSS} ${platform.displayName}: ${linkedCount}/${expected} skills linked${pluginNote} (${problems.join('; ')})`
+      );
       issues += missing.length + broken.length;
 
       // Collect symlink issues for detailed report
@@ -117,6 +143,27 @@ export async function doctorCommand() {
     }
   }
 
+  // Marketplace plugin
+  //
+  // Worth its own section because the two channels look identical from the
+  // outside and produce opposite expectations: with the plugin enabled, absent
+  // mirrors are correct; without it, absent mirrors mean no skills at all.
+  console.log('');
+  console.log('  Marketplace plugin:');
+  const pluginEnabled = isClaudePluginEnabled(homeDir);
+  const pluginCached = hasClaudePluginCache(homeDir);
+
+  if (pluginEnabled) {
+    console.log(`    ${CHECK} Enabled — Claude Code is served by the plugin, mirrors intentionally absent`);
+  } else if (pluginCached) {
+    console.log(`    ${WARN} Not enabled, but a cache directory remains from a previous install`);
+    console.log(`      ${chalk.dim('Harmless on this version. On aiskills < 1.16.1 it made install skip')}`);
+    console.log(`      ${chalk.dim('every symlink, leaving Claude Code with no skills. Remove it with:')}`);
+    console.log(`      ${chalk.cyan('rm -rf ~/.claude/plugins/cache/maccesar-aiskills')}`);
+  } else {
+    console.log(`    ${CHECK} Not installed — skills reach Claude Code through npm mirrors`);
+  }
+
   // Symlink issues detail
   if (symlinkIssues.length > 0) {
     console.log('');

package/lib/commands/skills.js

@@ -79,10 +79,12 @@ export async function skillsCommand(options) {
     chalk.dim('(agentskills.io standard)')
   );
   console.log(
-    '  ' + chalk.dim('Read directly by Gemini, Codex, Cursor, Cline, Amp, GitHub Copilot, +more.')
+    '  ' + chalk.green('✓'),
+    chalk.dim('Gemini, Codex, Cursor, Cline, Amp, GitHub Copilot +more read it directly —')
   );
+  console.log('    ' + chalk.dim('nothing else to configure for them.'));
   console.log(
-    '  ' + chalk.dim('Below: extra symlink mirrors for Claude Code.')
+    '  ' + chalk.dim('Claude Code needs symlink mirrors, created below.')
   );
   console.log('');
 
@@ -112,10 +114,19 @@ export async function skillsCommand(options) {
     process.exit(1);
   }
 
-  // Show detected platforms
+  // Show detected platforms.
+  //
+  // Only assistants that need aiskills-managed mirrors appear here, so a bare
+  // "Claude Code detected" reads as if the other assistants were not found at
+  // all. They were never looked for: Gemini, Codex and the rest read
+  // ~/.agents/skills/ directly and are already served by the install itself.
   if (detectedPlatforms.length > 0) {
     for (const platform of detectedPlatforms) {
-      console.log(chalk.green('✓'), `${platform.displayName} detected`);
+      console.log(
+        chalk.green('✓'),
+        `${platform.displayName} detected`,
+        chalk.dim('— needs mirrors, linked below')
+      );
     }
     console.log('');
   } else if (isLocal) {
@@ -269,6 +280,10 @@ export async function skillsCommand(options) {
           spinner.succeed(
             `${commandsResult.installed.length} slash command${commandsResult.installed.length !== 1 ? 's' : ''} installed`
           );
+        } else if (commandsResult.skipped.length > 0) {
+          spinner.info(
+            `${commandsResult.skipped.length} slash command${commandsResult.skipped.length !== 1 ? 's' : ''} already provided by the marketplace plugin`
+          );
         } else {
           spinner.info('No slash commands to install');
         }

package/lib/commands/update.js

@@ -67,6 +67,10 @@ async function performUpdate(baseDir, repoDir, spinner) {
       spinner.succeed(
         `${commandsResult.installed.length} slash command${commandsResult.installed.length !== 1 ? 's' : ''} synced`
       );
+    } else if (commandsResult.skipped.length > 0) {
+      spinner.info(
+        `${commandsResult.skipped.length} slash command${commandsResult.skipped.length !== 1 ? 's' : ''} already provided by the marketplace plugin`
+      );
     } else {
       spinner.info('No slash commands to sync');
     }

package/lib/config.js

@@ -64,6 +64,17 @@ export const CLAUDE_PLUGIN_NAME = 'aiskills';
 export const getClaudePluginSkillsPath = (baseDir = os.homedir()) =>
   path.join(baseDir, '.claude', 'plugins', 'cache', CLAUDE_PLUGIN_MARKETPLACE, CLAUDE_PLUGIN_NAME);
 
+// The key Claude Code writes under "enabledPlugins" when the plugin is installed.
+export const CLAUDE_PLUGIN_KEY = `${CLAUDE_PLUGIN_NAME}@${CLAUDE_PLUGIN_MARKETPLACE}`;
+
+// Where Claude Code records which plugins are enabled. Both files are consulted
+// because the local variant overrides the shared one, and either may carry the
+// entry depending on how the plugin was installed.
+export const getClaudeSettingsPaths = (baseDir = os.homedir()) => [
+  path.join(baseDir, '.claude', 'settings.json'),
+  path.join(baseDir, '.claude', 'settings.local.json'),
+];
+
 // AI platform detection
 //
 // Only platforms that need aiskills-managed symlinks appear here.

package/lib/installer.js

@@ -135,6 +135,7 @@ export async function installCommands(repoDir, baseDir = os.homedir()) {
     installed: [],
     failed: [],
     removed: [],
+    skipped: [],
   };
 
   const legacyLocal = removeCommands(baseDir, { legacyOnly: true });
@@ -147,7 +148,24 @@ export async function installCommands(repoDir, baseDir = os.homedir()) {
     results.failed.push(...legacyGlobal.failed);
   }
 
+  const { pluginProvidesCommand } = await import('./claude-plugin.js');
+  const commandsDir = getClaudeCommandsDir(baseDir);
+
   for (const cmd of COMMANDS) {
+    // Same rule the symlink step applies to skills: when the marketplace plugin
+    // already provides the command, installing our own copy makes it show up
+    // twice in the autocomplete. Clean up any copy left from before the plugin
+    // was installed.
+    if (pluginProvidesCommand(cmd, baseDir)) {
+      const stalePath = join(commandsDir, `${cmd}.md`);
+      if (existsSync(stalePath)) {
+        await remove(stalePath);
+        results.removed.push(cmd);
+      }
+      results.skipped.push(cmd);
+      continue;
+    }
+
     if (await installCommand(repoDir, cmd, baseDir)) {
       results.installed.push(cmd);
     } else {

package/lib/symlink.js

@@ -75,21 +75,16 @@ async function removePath(path) {
  * and an additional symlink at ~/.claude/skills/<skill> produces a duplicate
  * entry in the slash-command autocomplete. This helper lets the symlink step
  * skip Claude when the plugin already covers it.
+ *
+ * Requires the plugin to be *enabled*, not merely cached — see `claude-plugin.js`
+ * for why the distinction matters.
  * @param {string} skillName - Skill name (e.g. 'stitch-showcase')
  * @param {string} baseDir - Optional base directory (defaults to homedir via config)
  * @returns {Promise<boolean>} True if the plugin provides this skill
  */
 export async function isClaudePluginSkillInstalled(skillName, baseDir) {
-  const { readdir } = await import('fs/promises');
-  const { getClaudePluginSkillsPath } = await import('./config.js');
-  const pluginBase = getClaudePluginSkillsPath(baseDir);
-  if (!existsSync(pluginBase)) return false;
-  try {
-    const versions = await readdir(pluginBase);
-    return versions.some((v) => existsSync(join(pluginBase, v, 'skills', skillName)));
-  } catch {
-    return false;
-  }
+  const { pluginProvidesSkill } = await import('./claude-plugin.js');
+  return pluginProvidesSkill(skillName, baseDir);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maccesar/aiskills",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "AI coding assistant skills for Claude Code, Gemini CLI, and Codex CLI",
   "type": "module",
   "bin": {
@@ -53,7 +53,8 @@
   "files": [
     "bin/",
     "lib/",
-    "skills/"
+    "skills/",
+    "commands/"
   ],
   "publishConfig": {
     "access": "public"

package/skills/humaniza/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: humaniza
-description: 'Úsalo cuando humanices textos en español (especialmente es-MX) — editando emails, documentación, marketing, soporte o textos técnicos, eliminando patrones típicos de IA y devolviendo una versión natural y clara. Triggers: "humanizar", "hacerlo más natural", "quitar tono IA", "hacerlo sonar humano".'
+description: 'Editor de estilo para textos en español (especialmente es-MX): quita los tics de escritura de IA y devuelve prosa natural, concreta y directa, sin cambiar el contenido. Úsalo siempre que alguien quiera revisar, pulir o reescribir un texto en español —emails, documentación, marketing, soporte, posts, textos técnicos— aunque nunca diga "humanizar": "esto suena a ChatGPT", "quítale lo robótico", "hazlo más natural", "que no parezca IA", "sonó muy acartonado", "límale el tono", "revísame este correo antes de mandarlo". También cuando el texto mismo trae las señales: rayas por todas partes, "no es X, sino Y", "cabe destacar", listas de tres, abridores como "la verdad es que". No es para: traducir, corregir solo ortografía o gramática, escribir un texto desde cero, ni editar textos en inglés.'
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash, AskUserQuestion
 ---
 

package/skills/refactoring-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refactoring-ui
-description: 'Use when the user asks for UI/UX design advice, design reviews, visual hierarchy improvements, color system help, typography guidance, spacing decisions, depth/shadow usage, image handling, or finishing touches on any interface. Inspired by "Refactoring UI" by Adam Wathan & Steve Schoger. Triggers: "how do I make this look better?", color palettes, type scales, spacing systems, visual hierarchy, design reviews, shadows/depth, image handling, empty states, borders.'
+description: 'Design advice grounded in the principles of "Refactoring UI" by Adam Wathan & Steve Schoger. Use this whenever someone is trying to make an interface look better, or asks about visual hierarchy, color palettes and greys, type scales, spacing systems, shadows and depth, images, empty states, borders, dark mode, motion and hover states, or the layout of a modal, form or table — including when they never say "design" and just paste a component asking why it looks off, or say it "feels cramped", "looks generic", "needs polish", "how do I make this look better?". Applies to any stack: Tailwind, plain CSS, React, Blade, mobile. Not for: writing the copy itself, logo or brand identity work, user research, or debugging CSS that renders wrong.'
 ---
 
 # Refactoring UI Skill
@@ -17,13 +17,13 @@ SKILL.md is not enough.**
 
 | Task involves | Required reading |
 |---|---|
-| Color systems, typography, spacing scales — defining the system | [references/01-foundations.md](references/01-foundations.md) |
-| Layout, white space, visual hierarchy, page-level structure | [references/02-page-mechanics.md](references/02-page-mechanics.md) |
-| Color usage, HSL, greys, contrast, shadows, depth, images | [references/03-visual-treatment.md](references/03-visual-treatment.md) |
-| Empty states, borders, accents, finishing touches | [references/04-polish.md](references/04-polish.md) |
-| Motion, microinteractions, transitions, hover/press states, loading | [references/05-motion.md](references/05-motion.md) |
-| Dark mode, multi-theme color tokens, theme toggle, contrast strategy | [references/06-dark-mode.md](references/06-dark-mode.md) |
-| Modals, forms, tables — component-specific layout and behavior patterns | [references/07-component-patterns.md](references/07-component-patterns.md) |
+| Project mindset: feature-first work, scope discipline, defining systems, picking a voice | [references/01-foundations.md](references/01-foundations.md) |
+| Visual hierarchy, layout, white space, spacing scales, typography | [references/02-page-mechanics.md](references/02-page-mechanics.md) |
+| Color systems (HSL, shades, greys, contrast), depth and shadows, image handling | [references/03-visual-treatment.md](references/03-visual-treatment.md) |
+| Empty states, borders, accents, decorative defaults, finishing touches | [references/04-polish.md](references/04-polish.md) |
+| Motion, microinteractions, transitions, hover/press states, loading, `prefers-reduced-motion` — *complementary, not from the book* | [references/05-motion.md](references/05-motion.md) |
+| Dark mode, multi-theme color tokens, theme toggle, contrast strategy — *complementary, extrapolates the book's HSL principles* | [references/06-dark-mode.md](references/06-dark-mode.md) |
+| Modals (focus, layout), forms (labels, validation), tables (density, alignment) — *complementary, extends the book's principles* | [references/07-component-patterns.md](references/07-component-patterns.md) |
 
 ### Step 2 — Output contract
 
@@ -41,38 +41,17 @@ prepend `FROM_MEMORY (unverified):` to that claim. Do not hide it.
 
 ### Banned behaviors
 
-- ❌ Inventing ratios, scale values, contrast numbers, or rules not in the references
-- ❌ Reproducing the book's prose, illustrations, or examples verbatim — paraphrase only
-- ❌ Mixing in advice from unrelated design systems (Material, HIG, Tailwind defaults) as if it were *Refactoring UI* doctrine
-- ❌ Marking the answer complete without listing which reference files you read
+These four are where advice like this usually goes wrong, so they're worth naming:
 
-## When to use
-
-- User asks "how do I make this look better?"
-- User asks about color palettes, type scales, or spacing systems
-- User asks about visual hierarchy or emphasis
-- User is designing a UI component, page, or layout
-- User wants a design review or critique
-- User asks about shadows, depth, or layering
-- User asks about handling images in UI
-- User asks about empty states, borders, or decorative elements
+- Inventing ratios, scale values, contrast numbers, or rules not in the references. A made-up number is indistinguishable from a real one once it's in someone's stylesheet.
+- Reproducing the book's prose, illustrations, or examples verbatim. The references paraphrase on purpose — the original material belongs to its authors and is worth buying.
+- Presenting advice from unrelated design systems (Material, HIG, Tailwind defaults) as *Refactoring UI* doctrine. Those systems are fine; attributing them here makes the citation meaningless.
+- Marking the answer complete without listing which reference files you read. The list is what lets the reader tell a grounded answer from a plausible one.
 
 ## Source
 
 Inspired by 'Refactoring UI' by Adam Wathan & Steve Schoger — refactoringui.com
 
-## Reference Files
-
-| File                                | Topics                                                                                  |
-| ----------------------------------- | --------------------------------------------------------------------------------------- |
-| `references/01-foundations.md`      | Project mindset: feature-first work, scope discipline, defining systems, picking a voice |
-| `references/02-page-mechanics.md`   | Visual hierarchy, layout, white space, spacing scales, typography                       |
-| `references/03-visual-treatment.md` | Color systems (HSL, shades, greys, contrast), depth and shadows, image handling         |
-| `references/04-polish.md`           | Finishing touches: borders, accents, empty states, decorative defaults, design intuition |
-| `references/05-motion.md`           | Motion system (durations, easings), hover/press states, loading patterns, prefers-reduced-motion — **complementary** (not from RUI) |
-| `references/06-dark-mode.md`        | Dark mode color tokens, text contrast, shadow handling, images, theme toggle — **complementary** (extrapolates RUI's HSL principles) |
-| `references/07-component-patterns.md` | Modals (focus, layout), forms (labels, validation), tables (density, alignment) — **complementary** (extends RUI principles to specific components) |
-
 ## Anti-Patterns to Watch For
 
 - Designing layouts/navs/shells before designing real features [source: references/01-foundations.md]
@@ -84,6 +63,25 @@ Inspired by 'Refactoring UI' by Adam Wathan & Steve Schoger — refactoringui.co
 - Designing with placeholder images instead of real content [source: references/03-visual-treatment.md]
 - Shrinking a logo down to use as a favicon [source: references/03-visual-treatment.md]
 - Using preprocessor `lighten()` / `darken()` to derive shades [source: references/03-visual-treatment.md]
+- Leaving an empty state as a bare "No data" rectangle — it's often the first thing a new user sees [source: references/04-polish.md]
+- Rendering tabs, filters or pagination that have nothing to operate on (reads as broken) [source: references/04-polish.md]
+- Reaching for a border when a shadow, a second background color, or more space separates better [source: references/04-polish.md]
+- Shipping browser-default bullets, checkboxes and radios [source: references/04-polish.md]
+- Animating layout properties (`width`, `top`, `margin`) instead of `transform` / `opacity` [source: references/05-motion.md]
+- Inventing a duration per component instead of picking from a fixed motion scale [source: references/05-motion.md]
+- Scaling a whole element up on hover (1.05×), or animating font size [source: references/05-motion.md]
+- Showing a spinner before ~150ms of waiting [source: references/05-motion.md]
+- Ignoring `prefers-reduced-motion` [source: references/05-motion.md]
+- Pure `#000` for the canvas, or pure white for text [source: references/06-dark-mode.md]
+- Producing dark mode with `filter: invert(1)` [source: references/06-dark-mode.md]
+- Reusing the light-mode brand color in dark mode without rechecking contrast [source: references/06-dark-mode.md]
+- Applying the theme after first paint (flash of the wrong theme on every load) [source: references/06-dark-mode.md]
+- Keeping every light-mode shadow unchanged on a dark canvas, where it's invisible [source: references/06-dark-mode.md]
+- Using a placeholder as the only label [source: references/07-component-patterns.md]
+- Validating a field on every keystroke instead of on blur [source: references/07-component-patterns.md]
+- A modal with no focus trap, or centered vertically instead of anchored near the top [source: references/07-component-patterns.md]
+- Left-aligning numeric columns, which hides magnitude [source: references/07-component-patterns.md]
+- A translucent sticky table header, with rows showing through it [source: references/07-component-patterns.md]
 
 ## Attribution
 

package/skills/session-log/SKILL.md

@@ -93,53 +93,25 @@ repositories. Very often it's also **one working session**: someone adds an
 endpoint on the API side and, without switching context, wires the app that
 consumes it. The work is a single thought; only the folders are separate.
 
-**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
+**Install from inside each repo, separately**, and let each keep its own
+`status.md` — two repos have two branches, two deploy states and two histories, so
+one shared file goes stale on whichever side isn't being edited. 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.
-
-Each keeps its own `status.md` — two repos have two branches, two deploy states
-and two histories, and one shared file would go stale on whichever side isn't
-being edited.
-
-Put the sibling's **path** in the header, 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.
+outside, and the result reads like it.
 
 **When a session touched both, close both.** This is the part that gets skipped,
 and it's where the two halves drift into separate realities: the mobile notes say
 "waiting on the API" for three weeks while the backend's notes never mention that
-anything is waiting. If you added the endpoint and consumed it in the same
-session, both `status.md` files changed — write both before finishing.
-
-Even then, 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.
-
-If the sibling isn't reachable from where you're working, say so in the handoff
-rather than guessing at its state. "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.
+anything is waiting. Write each side from what you did to it, not from what you
+assume about it — and if you couldn't reach the sibling, say that in the handoff
+instead of guessing at its state.
 
 A **monorepo** is the opposite case and takes the opposite answer — one
 `docs/project/` at the root, packages as headings — because one repo has one branch,
 one deploy and one history to describe. And `status.md` being rewritten whole every
 session makes it **conflict-prone the moment a second person or branch touches it**.
-Both cases are in `references/file-layout.md`; neither comes up on a project with one
-person and one branch, which is most of them.
+All three cases, with the sibling header format, are in `references/file-layout.md`;
+none comes up on a project with one person and one branch, which is most of them.
 
 ### Why status.md is not loaded at startup
 

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

@@ -3,6 +3,19 @@
 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
 
 ```
@@ -87,6 +100,41 @@ Resolve conflicts by **keeping both sides and merging by section** — two peopl
 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`

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)