create-m5kdev 0.41.0 → 0.41.1

package/templates/minimal-app/apps/server/drizzle/meta/_journal.json.tpl

@@ -1,76 +1,76 @@
-{
-  "version": "7",
-  "dialect": "sqlite",
-  "entries": [
-    {
-      "idx": 0,
-      "version": "6",
-      "when": 1787759631723,
-      "tag": "0000_whole_echo",
-      "breakpoints": true
-    },
-    {
-      "idx": 1,
-      "version": "6",
-      "when": 1788197370969,
-      "tag": "0001_yummy_spectrum",
-      "breakpoints": true
-    },
-    {
-      "idx": 2,
-      "version": "6",
-      "when": 1788197859737,
-      "tag": "0002_crazy_lilith",
-      "breakpoints": true
-    },
-    {
-      "idx": 3,
-      "version": "6",
-      "when": 1788198203749,
-      "tag": "0003_freezing_fantastic_four",
-      "breakpoints": true
-    },
-    {
-      "idx": 4,
-      "version": "6",
-      "when": 1788198833389,
-      "tag": "0004_slow_ezekiel_stane",
-      "breakpoints": true
-    },
-    {
-      "idx": 5,
-      "version": "6",
-      "when": 1788253467922,
-      "tag": "0005_wonderful_the_professor",
-      "breakpoints": true
-    },
-    {
-      "idx": 6,
-      "version": "6",
-      "when": 1788787832546,
-      "tag": "0006_lazy_blue_marvel",
-      "breakpoints": true
-    },
-    {
-      "idx": 7,
-      "version": "6",
-      "when": 1788788533642,
-      "tag": "0007_abnormal_ultimo",
-      "breakpoints": true
-    },
-    {
-      "idx": 8,
-      "version": "6",
-      "when": 1788789159968,
-      "tag": "0008_steady_nekra",
-      "breakpoints": true
-    },
-    {
-      "idx": 9,
-      "version": "6",
-      "when": 1791905282553,
-      "tag": "0009_empty_starjammers",
-      "breakpoints": true
-    }
-  ]
-}
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1787759631723,
+      "tag": "0000_whole_echo",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1788197370969,
+      "tag": "0001_yummy_spectrum",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "6",
+      "when": 1788197859737,
+      "tag": "0002_crazy_lilith",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "6",
+      "when": 1788198203749,
+      "tag": "0003_freezing_fantastic_four",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "6",
+      "when": 1788198833389,
+      "tag": "0004_slow_ezekiel_stane",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "6",
+      "when": 1788253467922,
+      "tag": "0005_wonderful_the_professor",
+      "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "6",
+      "when": 1788787832546,
+      "tag": "0006_lazy_blue_marvel",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1788788533642,
+      "tag": "0007_abnormal_ultimo",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "6",
+      "when": 1788789159968,
+      "tag": "0008_steady_nekra",
+      "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1791905282553,
+      "tag": "0009_empty_starjammers",
+      "breakpoints": true
+    }
+  ]
+}

package/templates/minimal-app/apps/server/package.json.tpl

@@ -1,57 +1,57 @@
-{
-  "name": "{{PACKAGE_SCOPE}}/server",
-  "version": "0.0.0",
-  "private": true,
-  "main": "dist/index.js",
-  "scripts": {
-    "dev": "tsx watch --env-file=../shared/.env src/index.ts",
-    "build": "tsup",
-    "start": "node dist/index.js",
-    "lint": "biome check .",
-    "lint:fix": "biome check . --write",
-    "check-types": "tsc --noEmit",
-    "drizzle:generate": "drizzle-kit generate",
-    "drizzle:migrate": "drizzle-kit migrate",
-    "drizzle:studio": "drizzle-kit studio",
-    "drizzle:sync": "tsx --env-file=../shared/.env db.ts sync",
-    "drizzle:seed": "tsx --env-file=../shared/.env db.ts seed",
-    "drizzle:reset": "tsx --env-file=../shared/.env db.ts reset"
-  },
-  "dependencies": {
-    "{{PACKAGE_SCOPE}}/email": "workspace:*",
-    "{{PACKAGE_SCOPE}}/shared": "workspace:*",
-    "@libsql/client": "catalog:m5kdev",
-    "@m5kdev/backend": "catalog:m5kdev",
-    "@m5kdev/commons": "catalog:m5kdev",
-    "@mastra/core": "catalog:m5kdev",
-    "@openrouter/ai-sdk-provider": "catalog:m5kdev",
-    "@opentelemetry/api": "catalog:m5kdev",
-    "@trpc/server": "catalog:m5kdev",
-    "better-auth": "catalog:m5kdev",
-    "dotenv": "catalog:m5kdev",
-    "drizzle-orm": "catalog:m5kdev",
-    "drizzle-zod": "catalog:m5kdev",
-    "express": "catalog:m5kdev",
-    "ioredis": "catalog:m5kdev",
-    "neverthrow": "catalog:m5kdev",
-    "react": "catalog:m5kdev",
-    "react-dom": "catalog:m5kdev",
-    "uuid": "catalog:m5kdev",
-    "zod": "catalog:m5kdev"
-  },
-  "devDependencies": {
-    "@m5kdev/config": "catalog:m5kdev",
-    "@types/express": "catalog:m5kdev",
-    "@types/node": "catalog:m5kdev",
-    "@types/react": "catalog:m5kdev",
-    "@types/react-dom": "catalog:m5kdev",
-    "drizzle-kit": "catalog:m5kdev",
-    "tslib": "catalog:m5kdev",
-    "tsup": "catalog:m5kdev",
-    "tsx": "catalog:m5kdev",
-    "typescript": "catalog:m5kdev"
-  },
-  "exports": {
-    "./types": "./src/types.ts"
-  }
-}
+{
+  "name": "{{PACKAGE_SCOPE}}/server",
+  "version": "0.0.0",
+  "private": true,
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "tsx watch --env-file=../shared/.env src/index.ts",
+    "build": "tsup",
+    "start": "node dist/index.js",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "check-types": "tsc --noEmit",
+    "drizzle:generate": "drizzle-kit generate",
+    "drizzle:migrate": "drizzle-kit migrate",
+    "drizzle:studio": "drizzle-kit studio",
+    "drizzle:sync": "tsx --env-file=../shared/.env db.ts sync",
+    "drizzle:seed": "tsx --env-file=../shared/.env db.ts seed",
+    "drizzle:reset": "tsx --env-file=../shared/.env db.ts reset"
+  },
+  "dependencies": {
+    "{{PACKAGE_SCOPE}}/email": "workspace:*",
+    "{{PACKAGE_SCOPE}}/shared": "workspace:*",
+    "@libsql/client": "catalog:m5kdev",
+    "@m5kdev/backend": "catalog:m5kdev",
+    "@m5kdev/commons": "catalog:m5kdev",
+    "@mastra/core": "catalog:m5kdev",
+    "@openrouter/ai-sdk-provider": "catalog:m5kdev",
+    "@opentelemetry/api": "catalog:m5kdev",
+    "@trpc/server": "catalog:m5kdev",
+    "better-auth": "catalog:m5kdev",
+    "dotenv": "catalog:m5kdev",
+    "drizzle-orm": "catalog:m5kdev",
+    "drizzle-zod": "catalog:m5kdev",
+    "express": "catalog:m5kdev",
+    "ioredis": "catalog:m5kdev",
+    "neverthrow": "catalog:m5kdev",
+    "react": "catalog:m5kdev",
+    "react-dom": "catalog:m5kdev",
+    "uuid": "catalog:m5kdev",
+    "zod": "catalog:m5kdev"
+  },
+  "devDependencies": {
+    "@m5kdev/config": "catalog:m5kdev",
+    "@types/express": "catalog:m5kdev",
+    "@types/node": "catalog:m5kdev",
+    "@types/react": "catalog:m5kdev",
+    "@types/react-dom": "catalog:m5kdev",
+    "drizzle-kit": "catalog:m5kdev",
+    "tslib": "catalog:m5kdev",
+    "tsup": "catalog:m5kdev",
+    "tsx": "catalog:m5kdev",
+    "typescript": "catalog:m5kdev"
+  },
+  "exports": {
+    "./types": "./src/types.ts"
+  }
+}

package/templates/minimal-app/apps/server/src/app.ts.tpl

@@ -1,3 +1,4 @@
+// biome-ignore-all assist/source/organizeImports: feature-gated module imports stay in marker blocks
 import { createBackendApp } from "@m5kdev/backend/app";
 import { shutdownTelemetry } from "@m5kdev/backend/lib/otel";
 // m5k:ai:start

package/templates/minimal-app/apps/shared/package.json.tpl

@@ -1,27 +1,27 @@
-{
-  "name": "{{PACKAGE_SCOPE}}/shared",
-  "version": "0.0.0",
-  "private": true,
-  "scripts": {
-    "build": "tsc --noEmit",
-    "lint": "biome check .",
-    "lint:fix": "biome check . --write",
-    "check-types": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@m5kdev/commons": "catalog:m5kdev",
-    "zod": "catalog:m5kdev"
-  },
-  "devDependencies": {
-    "@m5kdev/config": "catalog:m5kdev",
-    "tslib": "catalog:m5kdev",
-    "typescript": "catalog:m5kdev"
-  },
-  "exports": {
-    "./modules/app/*": "./src/modules/app/*.ts",
-    "./modules/conversation/*": "./src/modules/conversation/*.ts",
-    "./modules/demo-workflow/*": "./src/modules/demo-workflow/*.ts",
-    "./modules/notification/*": "./src/modules/notification/*.ts",
-    "./modules/posts/*": "./src/modules/posts/*.ts"
-  }
-}
+{
+  "name": "{{PACKAGE_SCOPE}}/shared",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "check-types": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@m5kdev/commons": "catalog:m5kdev",
+    "zod": "catalog:m5kdev"
+  },
+  "devDependencies": {
+    "@m5kdev/config": "catalog:m5kdev",
+    "tslib": "catalog:m5kdev",
+    "typescript": "catalog:m5kdev"
+  },
+  "exports": {
+    "./modules/app/*": "./src/modules/app/*.ts",
+    "./modules/conversation/*": "./src/modules/conversation/*.ts",
+    "./modules/demo-workflow/*": "./src/modules/demo-workflow/*.ts",
+    "./modules/notification/*": "./src/modules/notification/*.ts",
+    "./modules/posts/*": "./src/modules/posts/*.ts"
+  }
+}

package/templates/minimal-app/apps/webapp/AGENTS.md.tpl

@@ -1,24 +1,24 @@
-# AGENTS.md
-
-## Frontend Stack
-
-- React 19 + TypeScript
-- React Router v7
-- HeroUI v3
-- Tailwind CSS v4
-- `nuqs` for URL state
-- TanStack Query + tRPC
-- i18next for all user-facing copy
-
-## Conventions
-
-- Keep providers centralized in `src/Providers.tsx`.
-- Keep routing in `src/Router.tsx`.
-- Keep feature code grouped under `src/modules/<feature>/` with `components/` and `hooks/` subfolders.
-- Prefer HeroUI primitives and existing framework utilities before adding custom abstractions.
-- Components stay display-focused: queries, mutations, URL state, and effects live in custom hooks (`hooks/use<Feature>Route.ts` composed from smaller hooks); ephemeral UI state (modal open, selected row) may stay in the component. Reusable tRPC actions (delete, publish) get their own hook.
-- Derive values during render instead of syncing state with `useEffect`.
-- Forms are uncontrolled: HeroUI `Form` + `TextField` with native HTML validation and `FieldError`, values read from `FormData` on submit. No form libraries. Extra checks that HTML validation cannot express happen in the submit handler.
-- Fetch through `useTRPC()` + `queryOptions`/`mutationOptions` only; invalidate with `queryFilter()` after mutations.
-- Use `useTranslation` for local app copy and rely on the bundled `web-ui` translations for auth routes.
-- The `posts` module is the reference implementation; detailed guides live in `.cursor/rules/frontend-*.mdc`.
+# AGENTS.md
+
+## Frontend Stack
+
+- React 19 + TypeScript
+- React Router v7
+- HeroUI v3
+- Tailwind CSS v4
+- `nuqs` for URL state
+- TanStack Query + tRPC
+- i18next for all user-facing copy
+
+## Conventions
+
+- Keep providers centralized in `src/Providers.tsx`.
+- Keep routing in `src/Router.tsx`.
+- Keep feature code grouped under `src/modules/<feature>/` with `components/` and `hooks/` subfolders.
+- Prefer HeroUI primitives and existing framework utilities before adding custom abstractions.
+- Components stay display-focused: queries, mutations, URL state, and effects live in custom hooks (`hooks/use<Feature>Route.ts` composed from smaller hooks); ephemeral UI state (modal open, selected row) may stay in the component. Reusable tRPC actions (delete, publish) get their own hook.
+- Derive values during render instead of syncing state with `useEffect`.
+- Forms are uncontrolled: HeroUI `Form` + `TextField` with native HTML validation and `FieldError`, values read from `FormData` on submit. No form libraries. Extra checks that HTML validation cannot express happen in the submit handler.
+- Fetch through `useTRPC()` + `queryOptions`/`mutationOptions` only; invalidate with `queryFilter()` after mutations.
+- Use `useTranslation` for local app copy and rely on the bundled `web-ui` translations for auth routes.
+- The `posts` module is the reference implementation; detailed guides live in `.cursor/rules/frontend-*.mdc`.

package/templates/minimal-app/apps/webapp/index.html.tpl

@@ -1,22 +1,22 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta
-      name="viewport"
-      content="width=device-width, initial-scale=1.0"
-    />
-    <meta
-      name="description"
-      content="The m5kdev starter application."
-    />
-    <title>{{APP_NAME}}</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script
-      type="module"
-      src="/src/main.tsx"
-    ></script>
-  </body>
-</html>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0"
+    />
+    <meta
+      name="description"
+      content="The m5kdev starter application."
+    />
+    <title>{{APP_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script
+      type="module"
+      src="/src/main.tsx"
+    ></script>
+  </body>
+</html>

package/templates/minimal-app/apps/webapp/package.json.tpl

@@ -1,53 +1,53 @@
-{
-  "name": "{{PACKAGE_SCOPE}}/webapp",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "lint": "biome check .",
-    "lint:fix": "biome check . --write",
-    "check-types": "tsc --noEmit",
-    "preview": "vite preview"
-  },
-  "dependencies": {
-    "{{PACKAGE_SCOPE}}/shared": "workspace:*",
-    "@heroui/react": "catalog:m5kdev",
-    "@heroui/styles": "catalog:m5kdev",
-    "@m5kdev/commons": "catalog:m5kdev",
-    "@m5kdev/frontend": "catalog:m5kdev",
-    "@m5kdev/web-ui": "catalog:m5kdev",
-    "@tanstack/react-query": "catalog:m5kdev",
-    "@trpc/client": "catalog:m5kdev",
-    "@trpc/tanstack-react-query": "catalog:m5kdev",
-    "better-auth": "catalog:m5kdev",
-    "i18next": "catalog:m5kdev",
-    "lucide-react": "catalog:m5kdev",
-    "nuqs": "catalog:m5kdev",
-    "posthog-js": "catalog:m5kdev",
-    "react": "catalog:m5kdev",
-    "react-dom": "catalog:m5kdev",
-    "react-hook-form": "catalog:m5kdev",
-    "react-i18next": "catalog:m5kdev",
-    "react-router": "catalog:m5kdev",
-    "sonner": "catalog:m5kdev",
-    "tailwindcss": "catalog:m5kdev",
-    "tw-animate-css": "catalog:m5kdev",
-    "zod": "catalog:m5kdev"
-  },
-  "devDependencies": {
-    "{{PACKAGE_SCOPE}}/server": "workspace:*",
-    "@m5kdev/config": "catalog:m5kdev",
-    "@tailwindcss/vite": "catalog:m5kdev",
-    "@types/react": "catalog:m5kdev",
-    "@types/react-dom": "catalog:m5kdev",
-    "@vitejs/plugin-react": "catalog:m5kdev",
-    "babel-plugin-react-compiler": "catalog:m5kdev",
-    "typescript": "catalog:m5kdev",
-    "vite": "catalog:m5kdev",
-    "vite-plugin-i18next-loader": "catalog:m5kdev",
-    "vite-tsconfig-paths": "catalog:m5kdev",
-    "@trpc/server": "catalog:m5kdev"
-  }
-}
+{
+  "name": "{{PACKAGE_SCOPE}}/webapp",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "check-types": "tsc --noEmit",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "{{PACKAGE_SCOPE}}/shared": "workspace:*",
+    "@heroui/react": "catalog:m5kdev",
+    "@heroui/styles": "catalog:m5kdev",
+    "@m5kdev/commons": "catalog:m5kdev",
+    "@m5kdev/frontend": "catalog:m5kdev",
+    "@m5kdev/web-ui": "catalog:m5kdev",
+    "@tanstack/react-query": "catalog:m5kdev",
+    "@trpc/client": "catalog:m5kdev",
+    "@trpc/tanstack-react-query": "catalog:m5kdev",
+    "better-auth": "catalog:m5kdev",
+    "i18next": "catalog:m5kdev",
+    "lucide-react": "catalog:m5kdev",
+    "nuqs": "catalog:m5kdev",
+    "posthog-js": "catalog:m5kdev",
+    "react": "catalog:m5kdev",
+    "react-dom": "catalog:m5kdev",
+    "react-hook-form": "catalog:m5kdev",
+    "react-i18next": "catalog:m5kdev",
+    "react-router": "catalog:m5kdev",
+    "sonner": "catalog:m5kdev",
+    "tailwindcss": "catalog:m5kdev",
+    "tw-animate-css": "catalog:m5kdev",
+    "zod": "catalog:m5kdev"
+  },
+  "devDependencies": {
+    "{{PACKAGE_SCOPE}}/server": "workspace:*",
+    "@m5kdev/config": "catalog:m5kdev",
+    "@tailwindcss/vite": "catalog:m5kdev",
+    "@types/react": "catalog:m5kdev",
+    "@types/react-dom": "catalog:m5kdev",
+    "@vitejs/plugin-react": "catalog:m5kdev",
+    "babel-plugin-react-compiler": "catalog:m5kdev",
+    "typescript": "catalog:m5kdev",
+    "vite": "catalog:m5kdev",
+    "vite-plugin-i18next-loader": "catalog:m5kdev",
+    "vite-tsconfig-paths": "catalog:m5kdev",
+    "@trpc/server": "catalog:m5kdev"
+  }
+}

package/templates/minimal-app/apps/webapp/public/logo.svg.tpl

@@ -1,6 +1,6 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="App logo">
-  <rect x="4" y="4" width="56" height="56" rx="14" fill="#b45309"/>
-  <path d="M20 18h18a6 6 0 0 1 6 6v22a2 2 0 0 1-3.2 1.6L36 44H20a4 4 0 0 1-4-4V22a4 4 0 0 1 4-4z" fill="#fffbeb"/>
-  <line x1="23" y1="27" x2="39" y2="27" stroke="#b45309" stroke-width="3" stroke-linecap="round"/>
-  <line x1="23" y1="34" x2="39" y2="34" stroke="#d97706" stroke-width="3" stroke-linecap="round"/>
-</svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="App logo">
+  <rect x="4" y="4" width="56" height="56" rx="14" fill="#b45309"/>
+  <path d="M20 18h18a6 6 0 0 1 6 6v22a2 2 0 0 1-3.2 1.6L36 44H20a4 4 0 0 1-4-4V22a4 4 0 0 1 4-4z" fill="#fffbeb"/>
+  <line x1="23" y1="27" x2="39" y2="27" stroke="#b45309" stroke-width="3" stroke-linecap="round"/>
+  <line x1="23" y1="34" x2="39" y2="34" stroke="#d97706" stroke-width="3" stroke-linecap="round"/>
+</svg>

package/templates/minimal-app/biome.json.tpl

@@ -14,6 +14,7 @@
       "!!**/storybook-static",
       "!**/.react-router",
       "!**/.m5kdev.json",
+      "!**/.e2e",
       "!**/drizzle/meta"
     ]
   },

package/templates/minimal-app/docs/agents/domain.md.tpl

@@ -0,0 +1,38 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`GLOSSARY.md`** at the repo root, or
+- **`GLOSSARY-MAP.md`** at the repo root if it exists — it points at one `GLOSSARY.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo:
+
+```
+/
+├── GLOSSARY.md
+├── docs/
+│   ├── agents/
+│   └── adr/
+│       ├── 0001-….md
+│       └── 0002-….md
+└── apps/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (…) — but worth reopening because…_

package/templates/minimal-app/docs/agents/issue-tracker.md.tpl

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v` — `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.