@simpleapps-com/augur-skills 0.0.18 → 0.0.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simpleapps-com/augur-skills",
-  "version": "0.0.18",
+  "version": "0.0.21",
   "description": "Install curated Claude Code skills",
   "license": "MIT",
   "type": "module",

package/skills/simpleapps/augur-packages/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: augur-packages
+description: Shared npm packages under @simpleapps-com/augur-*. Covers what each package provides, correct import patterns, key usage patterns, and what custom code they replace. Use when writing code for a site that consumes augur packages, during migration, or when deciding whether to write custom code.
+---
+
+# Augur Packages
+
+Shared npm packages for Next.js ecommerce sites and React Native apps. Published to npm under `@simpleapps-com`. Source: `simpleapps-com/augur-packages`.
+
+Before writing custom code, check whether a package export already solves the problem.
+
+## augur-utils
+
+Types, formatters, cache config. Zero framework dependencies. Works everywhere.
+
+```typescript
+import { formatPrice, CACHE_CONFIG } from "@simpleapps-com/augur-utils";
+import type { TCartLine, TProductItem } from "@simpleapps-com/augur-utils";
+import { cn } from "@simpleapps-com/augur-utils/web"; // clsx + tailwind-merge
+```
+
+**Types** cover: cart, category, inventory, product, pricing, attributes, UOM, supplier, filter, customer, menu, order, shipping, search, tax, metadata. Each has a Valibot schema (e.g., `CartLineSchema`).
+
+**Cache tiers** for React Query — every hook maps to one of these:
+
+| Tier | Use Case |
+|------|----------|
+| `CACHE_CONFIG.STATIC` | Rarely changes (categories, item master) |
+| `CACHE_CONFIG.SEMI_STATIC` | Changes occasionally (pricing, search) |
+| `CACHE_CONFIG.DYNAMIC` | Changes frequently (stock levels) |
+| `CACHE_CONFIG.CART` | User-specific, short-lived |
+| `CACHE_CONFIG.REALTIME` | Always refetch |
+
+## augur-web
+
+shadcn/Radix UI components. Per-component entry points — no barrel export, only what you import gets bundled.
+
+```typescript
+import { Button } from "@simpleapps-com/augur-web/button";
+import { Dialog, DialogContent, DialogTitle } from "@simpleapps-com/augur-web/dialog";
+import { Card, CardHeader, CardContent } from "@simpleapps-com/augur-web/card";
+```
+
+**Component conventions:** CVA variants, `React.forwardRef`, `asChild` via Radix Slot, `cn()` for class merging, `"use client"` preserved in build, `displayName` set, icons use `react-icons/lu`.
+
+**Tailwind content detection:** Tailwind v4 auto-detects sources. If augur-web classes are missing, add `@source "../node_modules/@simpleapps-com/augur-web/dist";` to your CSS.
+
+## augur-hooks
+
+React Query hooks and Zustand stores. Cross-platform (works in Next.js and React Native).
+
+```typescript
+// Cross-platform
+import { useItemPrice, useCartStore, useDebounce, AugurHooksProvider } from "@simpleapps-com/augur-hooks";
+// Web only (DOM-dependent)
+import { useIsMobile, useIsHydrated } from "@simpleapps-com/augur-hooks/web";
+```
+
+**Hook triple pattern** — every query hook exports three things:
+- `use<Name>(params, options?)` — client-side hook (reads SDK from provider context)
+- `get<Name>Options(api, params)` — server-side prefetch (accepts SDK directly)
+- `get<Name>Key(params)` — query key factory for cache invalidation
+
+```typescript
+// Client
+const { data } = useItemPrice(itemId, customerId, 1);
+
+// Server prefetch (no React context)
+await queryClient.prefetchQuery(getItemPriceOptions(api, itemId, customerId));
+
+// Cache invalidation
+queryClient.invalidateQueries({ queryKey: getItemPriceKey(itemId, customerId) });
+```
+
+**queryFn override** — web consumers can route through cached server actions:
+
+```typescript
+const { data } = useItemPrice(itemId, customerId, 1, {
+  queryFn: () => getCachedItemPrice(itemId, customerId, 1),
+});
+```
+
+**Cart hooks** use dependency injection — the package provides React Query orchestration (optimistic updates, invalidation, loading states), consumers inject site-specific mutation callbacks.
+
+**Provider required:** All query hooks need `AugurHooksProvider` wrapping the app with an SDK instance.
+
+## augur-server
+
+Server-side utilities for Next.js. Redis caching, auth factory, query client, environment detection.
+
+```typescript
+import { cachedSdkCall, getServerQueryClient, isDev, sdkCall } from "@simpleapps-com/augur-server";
+import { createAuthConfig } from "@simpleapps-com/augur-server/auth";
+```
+
+**cachedSdkCall** wraps SDK calls with Redis caching (SHA-256 key hashing, per-method stats, fire-and-forget writes, circuit breaker). Falls through without caching if ioredis is not installed.
+
+**createAuthConfig** — NextAuth 5 factory with dependency-injected callbacks:
+
+```typescript
+export const { handlers, signIn, signOut, auth } = NextAuth(
+  createAuthConfig({
+    callbacks: { getUserProfile, cartHdrLookup }, // site-specific
+    defaultCustomerId: process.env.NEXT_PUBLIC_DEFAULT_CUSTOMER_ID,
+  }),
+);
+```
+
+**Site action registry** — `createServerSite()` creates a process-global singleton. Self-heals via three-tier fallback (globalThis → module cache → auto-init from env vars).
+
+## augur-tailwind
+
+Tailwind v4 CSS theme. No `tailwind.config.ts` needed.
+
+```css
+@import "tailwindcss";
+@import "@simpleapps-com/augur-tailwind/base.css";
+@plugin "tailwindcss-animate";
+```
+
+Override brand with CSS variables: `--primary`, `--secondary`, `--radius`, etc. All HSL components (no wrapper).
+
+## What Stays Site-Specific
+
+MUST NOT be replaced by packages:
+- **Server actions** (`"use server"`) — site-specific business logic
+- **Layout components** (Header, Footer, MainMenu) — brand-specific
+- **Domain components** (ProductItem, CartTable, CategoryCard) — compose UI primitives
+- **Auth callbacks** (`getUserProfile`, `cartHdrLookup`) — injected into `createAuthConfig`
+- **Cart mutation callbacks** — depend on site-specific server actions
+- **CSS variable overrides** — brand colors, fonts, radius
+- **next.config** — image domains, redirects, security headers
+- **Site integrations** — GA4, Maps, reCAPTCHA
+
+## Anti-Pattern Catalog
+
+Custom code that duplicates package exports. When you see these in a site, replace with the package version.
+
+| Custom Code | Replace With |
+|-------------|-------------|
+| `cn()` in `@/lib/utils` | `cn` from `augur-utils/web` |
+| `formatPrice()` helpers | `formatPrice` from `augur-utils` |
+| Local types (`@/types/T*`) | Types from `augur-utils` |
+| Custom `CACHE_CONFIG` / inline TTLs | `CACHE_CONFIG` from `augur-utils` |
+| `@/components/ui/*` imports | `augur-web/<component>` |
+| Custom breadcrumb, quantity, pagination, form inputs | `augur-web/<component>` |
+| Custom `useDebounce` | `useDebounce` from `augur-hooks` |
+| Custom `useIsMobile` / `useIsHydrated` | From `augur-hooks/web` |
+| Custom price/cart hooks or stores | From `augur-hooks` |
+| Custom `cachedSdkCall` / SDK cache | `cachedSdkCall` from `augur-server` |
+| Custom `getServerQueryClient` | From `augur-server` |
+| Custom `isDev` / env detection | From `augur-server` |
+| Manual NextAuth Credentials config | `createAuthConfig` from `augur-server/auth` |
+| `lucide-react` / `@heroicons/react` | `react-icons/lu` |
+| `tailwind.config.ts` (v3) | `augur-tailwind/base.css` CSS-first |
+
+## Platform Standard
+
+- **Icons:** `react-icons/lu`
+- **Tailwind:** v4, CSS-first via `augur-tailwind/base.css`
+- **Validation:** Valibot (not Zod, not Yup)
+- **Auth:** NextAuth 5 via `createAuthConfig()`
+- **Reference site:** ampro-online

package/skills/simpleapps/{workflow/basecamp.md → basecamp/SKILL.md}

@@ -1,6 +1,11 @@
-# Basecamp 2 Reference
+---
+name: basecamp
+description: Basecamp 2 integration via MCP. Covers MCP tool reference, URL parsing, authentication, Chrome fallback, attachments, and site-info documents. Use when reading or writing Basecamp data.
+---
 
-IMPORTANT: YOU MUST NOT create, edit, or delete anything in Basecamp without user permission.
+# Basecamp 2
+
+IMPORTANT: MUST NOT create, edit, or delete anything in Basecamp without user permission.
 
 **Content format**: All write tools SHOULD use plain text with line breaks, NOT HTML. Basecamp returns HTML in responses but prefers plain text for creation.
 
@@ -14,7 +19,7 @@ uv run basecamp-auth
 
 This opens the browser for OAuth, user clicks "Allow", credentials are saved automatically.
 
-## MCP Tools (Preferred)
+## MCP Tools
 
 The `basecamp` MCP server is bundled with this plugin and starts automatically. API reference: https://github.com/basecamp/bcx-api
 
@@ -143,7 +148,11 @@ Note: Messages may not be available on all Basecamp plans.
 
 **Note**: The BCX API does not have a search endpoint. To find content, use `list_topics(project_id)` to browse, or `list_messages(project_id)` for messages. For cross-project browsing, use `list_topics()` (no project_id) to get recent topics across all projects.
 
-**Extracting IDs from Basecamp URLs**: A URL like `https://basecamp.com/2805226/projects/18932786/todos/514631271` gives you project_id=`18932786` and todo_id=`514631271`.
+## URL Parsing
+
+A URL like `https://basecamp.com/2805226/projects/18932786/todos/514631271` gives you project_id=`18932786` and todo_id=`514631271`.
+
+**Base URL**: `https://basecamp.com/2805226`
 
 ## Downloading Attachments
 
@@ -156,6 +165,10 @@ Attachments can be on todos, comments, messages, or uploads. To retrieve them:
 
 To browse all attachments in a project, use `list_attachments(project_id)`.
 
+## Site Info Documents
+
+Each Basecamp project SHOULD have a **site-info** text document in its Documents section. It contains site-specific details like siteId and domain name needed for GitHub issues and development work. Use `list_documents` + `get_document` to find it. If no site-info document exists, ask the user to create one.
+
 ## Chrome Fallback
 
 If the MCP server is unavailable (credentials expired, server not running), use Chrome:
@@ -165,8 +178,6 @@ If the MCP server is unavailable (credentials expired, server not running), use
 3. Navigate to the Basecamp page
 4. Use `get_page_text` to extract content
 
-**Base URL**: `https://basecamp.com/2805226`
-
 **Top nav**: Projects | Calendar | Everything | Progress | Everyone | **Me**
 
 | Page | Path |
@@ -182,14 +193,6 @@ If the MCP server is unavailable (credentials expired, server not running), use
 
 **JSON API via Chrome**: Navigate to `/api/v1/projects/<project_id>/todos/<todo_id>.json` then use `get_page_text`. WebFetch will NOT work — Chrome carries session cookies.
 
-## Fyxer Meeting Transcripts
-
-To post Fyxer meeting recordings as Basecamp Discussions, see the `simpleapps:fyxer` skill. It handles extraction, local caching, duplicate detection, and posting via `create_message`.
-
-## Site Info Documents
-
-Each Basecamp project SHOULD have a **site-info** text document in its Documents section. It contains site-specific details like siteId and domain name needed for GitHub issues and development work. Use `list_documents` + `get_document` to find it. If no site-info document exists, ask the user to create one.
-
 ## Tips
 
 - Cache the user's `person_id` on first visit for the session

package/skills/simpleapps/fyxer/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: fyxer
-description: Fyxer AI meeting recording integration. Covers extraction, local caching, and posting to downstream services. Use when processing Fyxer recordings or meeting transcripts.
+description: Fyxer AI meeting recording integration. Covers extraction, local caching, posting to Basecamp, and Fyxer Index management. Use when processing Fyxer recordings or meeting transcripts.
 ---
 
 # Fyxer
 
-Fyxer AI records and summarizes meetings. This skill covers extracting data from Fyxer and routing it to other services.
+Fyxer AI records and summarizes meetings. This skill covers extracting data from Fyxer, posting to Basecamp, and managing the Fyxer Index.
 
 ## Fyxer URLs
 
@@ -28,7 +28,7 @@ All extracted data is cached at `~/.simpleapps/fyxer/<meeting-uuid>/`:
 ```
 summary.txt     - raw Fyxer summary (from Summary tab)
 transcript.txt  - raw Fyxer transcript (from Transcript tab)
-message.txt     - assembled output (generated by downstream processes, e.g. basecamp.md)
+message.txt     - assembled output (generated by posting process)
 ```
 
 Cache is populated via Chrome extraction (see below) and reused across processes.
@@ -84,11 +84,125 @@ Then write and verify: `pbpaste > target.txt && wc -c target.txt`
 
 MUST clean up `~/Downloads/` after copying downloaded files to the cache directory. Fyxer names downloads like `transcript-SA_USCCO.txt`. Repeated downloads append `(1)`, `(2)`, etc.
 
-## Processes
+## Posting to Basecamp
 
-- See `basecamp.md` for posting meeting transcripts as Basecamp Discussions
-- See `basecamp-index.md` for the Fyxer Index document (duplicate detection, reconciliation)
+Post Fyxer meeting recordings as searchable Discussions in Basecamp projects.
+
+**Inputs**: Fyxer recording URL + Basecamp project ID.
+
+### 1. Check for duplicate
+
+Extract the meeting UUID from the Fyxer URL. Find the **Fyxer Index** document in the project: `list_documents(project_id)` → scan for title `Fyxer Index`. If found, `get_document(project_id, document_id)` and search content for the meeting UUID. If found, the meeting has already been posted — inform the user and stop.
+
+If no Fyxer Index document exists, there are no tracked meetings. Proceed with posting.
+
+### 2. Check local cache
+
+If `~/.simpleapps/fyxer/<meeting-uuid>/summary.txt` and `transcript.txt` both exist, skip to step 3. Otherwise, follow the Chrome extraction steps above.
+
+### 3. Build message.txt
+
+Parse `summary.txt` for frontmatter fields, extract participants, and combine with the full transcript:
+
+```
+---
+meeting: SA/ClientName
+date: YYYY-MM-DD
+time: HH:MM-HH:MM
+participants: Person A, Person B, Person C
+topics: Topic One, Topic Two, Topic Three
+fyxer-id: <meeting-uuid>
+---
+
+[contents of transcript.txt]
+```
+
+| Field | Source |
+|-------|--------|
+| meeting | Meeting title from the page header |
+| date | Recording date |
+| time | Recording time range |
+| participants | Participant dropdown (click to reveal names) |
+| topics | Section headings from the Summary |
+| fyxer-id | Meeting UUID from the URL (before the colon) |
+
+Save as `~/.simpleapps/fyxer/<meeting-uuid>/message.txt`.
+
+### 4. Post to Basecamp
+
+Use `create_message(project_id, subject, content)`:
+
+- **Subject**: `Fyxer: YYYY-MM-DD`
+- **Content**: contents of `message.txt`
+
+Capture the **message_id** from the response.
+
+### 5. Update Fyxer Index
+
+After a successful post, update the Fyxer Index document:
+
+1. If no Fyxer Index document exists, create one: `create_document(project_id, "Fyxer Index", "")`
+2. Read current content: `get_document(project_id, document_id)`
+3. Prepend a new line (newest first): `<meeting-uuid> | <date> | <message-id> | <subject>`
+4. Update: `update_document(project_id, document_id, title="Fyxer Index", content=updated_content)`
+
+If the index update fails after a successful post, warn the user. The message is posted but the index is stale. Run reconciliation later.
+
+### Format rules
+
+- **Plain text only** — Basecamp prefers plain text over HTML
+- **YAML frontmatter** — machine-parseable so other Claude Code instances can search and parse meeting context
+- **Transcript only in body** — summary and action items belong on relevant Basecamp todos, not in this message
+- **Consistent title** — `Fyxer: YYYY-MM-DD` keeps messages uniform and sortable
+
+## Fyxer Index
+
+Each Basecamp project that receives Fyxer meeting transcripts MUST have a **Fyxer Index** document for duplicate detection and meeting history.
+
+### Index format
+
+- **Title**: `Fyxer Index`
+- **Location**: Documents section of each Basecamp project
+- **Content**: One line per posted meeting, newest first
+
+```
+<meeting-uuid> | <date> | <message-id> | <subject>
+```
+
+Example:
+
+```
+52f0cf2b-fdb8-4e95-8b01-2afb6d367c69 | 2026-01-19 | 514789012 | Fyxer: 2026-01-19
+a1b2c3d4-e5f6-7890-abcd-ef1234567890 | 2026-02-10 | 514801234 | Fyxer: 2026-02-10
+```
+
+### Finding posted transcripts
+
+- Check the index: `list_documents(project_id)` → find `Fyxer Index` → `get_document`
+- View a specific transcript: `get_message(project_id, message_id)` using the message_id from the index
+- Browse all messages: `list_messages(project_id)` — Fyxer posts use the title format `Fyxer: YYYY-MM-DD`
+
+### Reconciliation — missing entries
+
+The index MAY fall out of sync. To reconcile:
+
+1. `list_messages(project_id)` → filter for `Fyxer:` titles
+2. For each, `get_message` and extract `fyxer-id` from YAML frontmatter
+3. Compare against the index — add any missing entries
+4. Update the index document
+
+Run reconciliation when the index is first created in a project with existing Fyxer messages, or when the user suspects the index is incomplete.
+
+### Reconciliation — orphaned entries
+
+If an index entry references a deleted message:
+
+1. `get_message(project_id, message_id)` → if 404, remove entry from index
+2. Update the index document
+
+Only run orphan cleanup when explicitly requested by the user.
 
 ## Dependencies
 
+- `simpleapps:basecamp` skill — MCP tools for posting and index management
 - Chrome browser automation (for extraction when cache is empty)

package/skills/simpleapps/github/SKILL.md

@@ -1,46 +1,89 @@
 ---
 name: github
-description: GitHub conventions for SimpleApps. Covers org structure, local project layout, wiki-as-docs workflow, issue creation, PR workflows, and gh CLI usage. Use when creating issues, PRs, setting up repos, or working with GitHub wikis.
+description: GitHub conventions for SimpleApps. Covers org structure, git safety, issue creation, PR workflows, and gh CLI usage. Use when creating issues, PRs, or working with GitHub repos.
+allowed-tools: Skill(project-defaults)
 ---
 
+First, use Skill("project-defaults") to load the project layout.
+
 # GitHub
 
 ## Organization
 
-All SimpleApps repos live under the **`simpleapps-com`** GitHub org.
-
-Repository pattern: `simpleapps-com/<repo-name>`
+All SimpleApps repos live under **`simpleapps-com`**. Pattern: `simpleapps-com/<repo-name>`
 
 ## Authentication
 
-Use the `gh` CLI for all GitHub operations:
-
 ```bash
-gh auth status          # Check auth status
-gh auth setup-git       # Configure gh as git credential helper
+gh auth status          # Check auth
+gh auth setup-git       # Fix git credential helper (run if push fails 401/403)
 ```
 
-If `git push` fails with 401/403, run `gh auth setup-git` to fix credentials.
+## Project Layout
 
-## Key Topics
+See `simpleapps:project-defaults` for the full directory layout, symlink setup, and permission defaults. Key point: the git repo is always at `repo/`. Use `git -C repo` for git operations from the project root.
 
-- **Wiki as context** — See `wiki-as-context.md` for why the wiki is the source of truth and how to write for both humans and AI agents.
-- **Wiki maintenance** — See `wiki-maintenance.md` for how to verify, update, and maintain wiki content correctly.
-- **Project structure** — See `project-structure.md` for the `{project}/[repo|wiki]` layout, what goes where, and wiki conventions.
-- **Issues & pull requests** — See `issues-prs.md` for issue templates, PR commands, and cross-linking with Basecamp.
+## Wiki
 
-## Quick Reference
+See `simpleapps:wiki` for wiki conventions, token budget, and maintenance rules.
 
-```bash
-# Pushing
-gh auth setup-git && git push origin <branch>
-git push origin <tag>
+## Git Safety
+
+MUST NOT commit, push, create PRs, or merge unless the user explicitly asks. After making changes, report what was done and stop. Do not offer or suggest the next git action — wait for instructions.
+
+- **Commits**: Do not commit until the user says "commit" or equivalent
+- **Pushes**: Do not push until the user explicitly asks
+- **PRs**: Do not create or offer to create a PR — report the work, stop
+- **Merges**: Do not merge unless the user explicitly asks
+
+The pattern is always: **do the work → report results → wait**.
+
+## Issues
+
+MUST use `--repo simpleapps-com/<repo>` on every `gh` call. MUST ask the user which repo — never assume.
+
+### Title
+
+Conventional commit style: `fix: description`, `feat: description`, `chore: description`. Under 70 characters.
+
+### Body
+
+```markdown
+## Problem
+What is broken, missing, or needed?
 
-# Issues
+## Expected Behavior
+What SHOULD happen instead?
+
+## Acceptance Criteria
+- [ ] Concrete, testable criteria
+
+## Context
+Related issues, affected files, workarounds, reproduction steps.
+```
+
+Bug reports also include **Steps to Reproduce** and **Current Behavior** with error messages.
+
+### Commands
+
+```bash
 gh issue create --repo simpleapps-com/<repo> --title "type: desc" --body "..."
 gh issue list --repo simpleapps-com/<repo>
+gh issue view <number> --repo simpleapps-com/<repo>
+gh issue close <number> --repo simpleapps-com/<repo> --comment "message"
+```
+
+Include `Closes #N` in commit body to auto-close issues.
+
+## Pull Requests
 
-# PRs
+```bash
 gh pr create --repo simpleapps-com/<repo> --title "title" --body "..."
 gh pr list --repo simpleapps-com/<repo>
+gh pr view <number> --repo simpleapps-com/<repo>
+gh pr merge <number> --repo simpleapps-com/<repo>
 ```
+
+## Cross-Linking with Basecamp
+
+For client tasks originating in Basecamp, see `simpleapps:workflow` for the full cross-linking process.

package/skills/simpleapps/project-defaults/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: project-defaults
+description: SimpleApps project conventions. Covers directory layout, symlink setup for .claude integration, permission defaults (deny cd, kill), and per-project baseline settings. Use when setting up projects, checking structure, or configuring Claude Code defaults.
+---
+
+# Project Defaults
+
+## Directory Layout
+
+Every project MUST use this layout:
+
+```
+{project}/
+├── .claude/            # Claude Code config (symlinks to repo/.claude/)
+│   ├── rules/          # → repo/.claude/rules/
+│   └── commands/       # → repo/.claude/commands/
+├── repo/               # Git repo (simpleapps-com/<name>.git)
+├── wiki/               # Wiki repo (simpleapps-com/<name>.wiki.git)
+├── wip/                # Work-in-progress files (not in git)
+├── tmp/                # Temporary files (not in git)
+└── .simpleapps/        # Credentials (not in git)
+```
+
+The parent `{project}/` is NOT a git repo — it keeps code and wiki side-by-side. The git repo is always at `repo/`. Use `git -C repo` for git operations from the project root.
+
+| Content | Location | Examples |
+|---------|----------|---------|
+| Product code | `repo/` | Source, tests, configs, SKILL.md files |
+| Dev documentation | `wiki/` | Architecture, guides, specs, conventions |
+| Repo `.claude/rules/` | `repo/` | Minimal summaries referencing wiki |
+| Repo `.claude/CLAUDE.md` | `repo/` | Quick reference + wiki links |
+| Active task context | `wip/` | `{issue-number}-{short-desc}.md` files |
+| Temporary files | `tmp/` | Throwaway files, scratch space, build artifacts |
+| Project secrets | `{project}/.simpleapps/` | Site-specific credentials |
+| Global secrets | `~/.simpleapps/` | Shared credentials across all projects |
+
+**WIP**: Research, plans, decisions, test results. MUST NOT contain secrets, final docs, or code.
+
+**Credentials**: Project-level (`.simpleapps/`) overrides user-level (`~/.simpleapps/`). MUST NOT be committed.
+
+## Symlink Setup
+
+The repo contains `.claude/rules/` and `.claude/commands/` with project-specific rules and commands. To make these active from the project root (without starting Claude Code inside `repo/`), symlink them into the project-level `.claude/` folder:
+
+```bash
+mkdir -p {project}/.claude
+ln -sf ../repo/.claude/rules {project}/.claude/rules
+ln -sf ../repo/.claude/commands {project}/.claude/commands
+```
+
+This lets you run Claude Code from `{project}/` and still get the repo's rules and commands loaded automatically.
+
+## Permission Defaults
+
+Every project SHOULD configure `.claude/settings.local.json` with these deny rules:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Bash(cd:*)",
+      "Bash(cat:*)",
+      "Bash(sed:*)",
+      "Bash(grep:*)",
+      "Bash(sleep:*)",
+      "Bash(kill:*)",
+      "Bash(pkill:*)"
+    ]
+  }
+}
+```
+
+Why each is denied:
+
+- **`cd`** — Use `git -C` or tool-specific flags (`--repo`, `-C`) instead. `cd` loses working directory context.
+- **`cat`** — Use the Read tool instead.
+- **`sed`** — Use the Edit tool instead.
+- **`grep`** — Use the Grep tool instead.
+- **`sleep`** — Unnecessary; use proper sequencing or background tasks.
+- **`kill`/`pkill`** — Use `TaskStop` to manage background processes. For internal tasks running in the background (dev servers, watchers, etc.), always use `TaskStop` instead of shell kill commands. `TaskStop` cleanly shuts down the task and updates Claude Code's internal tracking.
+
+## New Project Setup
+
+```bash
+mkdir {project} && cd {project}
+git clone https://github.com/simpleapps-com/<name>.git repo
+git clone https://github.com/simpleapps-com/<name>.wiki.git wiki
+mkdir -p wip tmp .simpleapps .claude
+ln -sf ../repo/.claude/rules .claude/rules
+ln -sf ../repo/.claude/commands .claude/commands
+```

package/skills/simpleapps/wiki/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: wiki
+description: Wiki conventions for SimpleApps projects. Covers token budget, writing for three audiences, page conventions, maintenance rules, and git workflow. Use when reading, writing, or auditing wiki content.
+---
+
+# Wiki
+
+The wiki is the **single source of truth** for how a project works. The wiki is the spec; the repo is the implementation.
+
+## Token Budget
+
+A wiki MUST NOT exceed **20K tokens** (~15K words, ~60KB). This is 10% of the AI agent's 200K context window — enough for the agent to load the entire wiki at session start while leaving 90% for working context.
+
+Check size: `wc -w wiki/*.md` (multiply by ~1.3 for token estimate)
+
+## Core Principle
+
+Repo files (`.claude/CLAUDE.md`, `.claude/rules/`, `README.md`) MUST be minimal — orient then point to wiki. AI agents read wiki pages as local files via `Read wiki/<page>.md`. No network requests needed.
+
+```
+Wiki defines → Code implements → Learnings update wiki → Repeat
+```
+
+When code reveals the wiki is wrong or incomplete, update immediately. The wiki MUST reflect reality, not aspirations.
+
+## Three Audiences
+
+Every page serves junior devs (explanations, examples), senior devs (quick reference, decisions), and AI agents (unambiguous specs, MUST/SHOULD/MAY). Write for all three:
+
+- Lead with a summary — seniors and agents get it fast, juniors get orientation
+- Explain *why* before *how*
+- Use tables for reference, code blocks for copy-paste, RFC 2119 keywords for requirements
+- Each page SHOULD be self-contained
+- Follow `simpleapps:writing-style` — token-efficient, action verbs first, no filler
+
+## Content Rules
+
+- Wiki pages SHOULD NOT contain raw code. Describe patterns and principles instead.
+- If implementation details are needed, link to the source file in `repo/` rather than duplicating code in the wiki.
+- The wiki documents *what* and *why*. The repo is the source of truth for *how*.
+
+## Conventions
+
+- Page naming: **PascalCase** with hyphens (`Getting-Started.md`)
+- Every wiki MUST have `_Sidebar.md` for navigation
+- Links: `[[Page-Name]]` or `[[Display Text|Page-Name]]`
+- Anchor links MUST target specific sections (`[[Versioning#version-bump-procedure]]`), not just pages
+- Repo references: use relative paths (`../../../wiki/Versioning.md`)
+- Default branch: `master` (not `main`)
+
+## Keep It Lean
+
+- Document patterns and principles, not exhaustive lists
+- No hardcoded counts, no pinned versions, no full export inventories
+- Describe the pattern, give 1-2 examples, point to source for current list
+- Merge overlapping pages, archive obsolete ones
+
+## Maintenance
+
+Cross-check wiki against code before updating. Staleness-prone: versions, file counts, CI workflows, TODO markers, API surfaces. **Never echo what the wiki says — read the code, then write.**
+
+When adding/removing pages, MUST update: `Home.md`, `_Sidebar.md`, `llms.txt` (if present).
+
+**Lead-site wikis** (e.g., ampro-online) serve as platform reference. Tag sections **(platform pattern)** vs **(site-specific)** so agents on other sites know what to replicate vs customize.
+
+## Git Workflow
+
+The wiki is a separate git repo at `wiki/`. No branch protection, no PRs.
+
+```bash
+git -C wiki add -A
+git -C wiki commit -m "docs: describe the change"
+git -C wiki push
+```