ai-spector 0.4.0 → 0.4.2

package/scaffold/cursor/skills/ai-spector/references/language-picker.md

@@ -0,0 +1,70 @@
+# Language picker — ask, store, enforce
+
+When **no document language is stored** and the user did not name one in this request, run this flow **before any document write**. Do not generate document content until the user confirms a language.
+
+Skip this flow when:
+
+- User named a language in this request ("write in Japanese", "use Vietnamese")
+- `.ai-spector/.docflow/config/language.json` already exists and has `documentLanguage` set (use it — do not re-ask)
+
+## Step 1 — Check for stored preference
+
+Read `.ai-spector/.docflow/config/language.json`. If the file exists and `documentLanguage` is a non-empty string, use that language for all document content. Skip the rest of this document.
+
+## Step 2 — Ask the user
+
+Post exactly this message and **stop**. Do not write any document content until the user replies.
+
+```
+What language should I use for all generated documents?
+
+  1. English
+  2. Japanese
+  3. Vietnamese
+
+Reply with **1**, **2**, or **3** — or type the language name directly.
+Once saved, all document content — headings, body, tables, labels — will be written in that language consistently.
+```
+
+Accept: `1` / `2` / `3`, or the language name typed directly (case-insensitive). Map to the canonical value:
+
+| Input | Stored as |
+|-------|-----------|
+| `1`, `english` | `English` |
+| `2`, `japanese` | `Japanese` |
+| `3`, `vietnamese` | `Vietnamese` |
+
+Any other input: reply "Please choose 1 (English), 2 (Japanese), or 3 (Vietnamese)." and wait again.
+
+## Step 3 — Persist the choice
+
+When the user replies, create or overwrite `.ai-spector/.docflow/config/language.json`:
+
+```json
+{
+  "version": 1,
+  "documentLanguage": "<user's answer>",
+  "setAt": "<ISO timestamp>"
+}
+```
+
+Then continue with document generation.
+
+## Changing the language later
+
+If the user says "change language to X" or "switch to X" at any time:
+- Accept only English, Japanese, or Vietnamese. For any other language, reply "Only English, Japanese, and Vietnamese are supported."
+- Update `language.json` with the new value.
+- Remind them that already-generated files keep their old language until regenerated.
+
+---
+
+## Enforcement rules (apply to every document write)
+
+After the language is known, apply these rules for **every file written**:
+
+1. **All content in the target language** — headings, body paragraphs, table cell values, labels, bullet text, notes, captions.
+2. **ID tokens are never translated** — UC-01, F-03, API slugs (`POST /checkout`), screen IDs (S-01), graph node IDs, file paths, CLI commands, code blocks. These stay in their original form.
+3. **Template structure labels are translated** — e.g. if the template says "## Overview", write the heading in the target language ("## 概要" for Japanese, "## Tổng quan" for Vietnamese, etc.).
+4. **Never mix languages** — do not write an English heading with a non-English body, or vice versa. If you catch a mixed-language draft, fix it before writing.
+5. **Quote source material faithfully, then translate inline** — if a `docs/data-source` file contains text in another language, you may reference its meaning in the target language rather than copying the foreign text into the output document.

package/scaffold/cursor/skills/ai-spector/references/project-conventions.md

@@ -19,9 +19,18 @@ Missing templates → `npx ai-spector init --force`.
 | Detail design | `docs/detail-design/` |
 | HTML prototype | `prototype/src/` |
 
+## Document language
+
+Stored in `.ai-spector/.docflow/config/language.json` (`documentLanguage` field).
+
+- **Before the first write** in any session, check this file. If `documentLanguage` is `null` or missing, run the language-picker flow ([language-picker.md](./language-picker.md)) — ask the user, persist the answer, then continue.
+- **All generated content** (headings, body, tables, labels) must be in `documentLanguage`. Identifiers (UC-01, F-02, API paths, code) are never translated.
+- Change with: edit `language.json` directly; already-generated files are not auto-updated.
+
 ## Generation discipline (all layers)
 
-1. Read template from `.ai-spector/templates/` — never invent section structure.
-2. Query graph before writing (`ai-spector graph query`).
-3. Merge projection patches after each wave (`graph merge`).
-4. Validate when the command doc requires it.
+1. **Check document language** ([language-picker.md](./language-picker.md)) before any write.
+2. Read template from `.ai-spector/templates/` — never invent section structure.
+3. Query graph before writing (`ai-spector graph query`).
+4. Merge projection patches after each wave (`graph merge`).
+5. Validate when the command doc requires it.

package/scaffold/cursor/skills/ai-spector-generate-basic-design/SKILL.md

@@ -23,6 +23,7 @@ paths:
 ## Checklist
 
 ```
+- [ ] language confirmed (language-picker.md — check before first write)
 - [ ] graph validate; SRS on disk
 - [ ] index after every wave (mandatory)
 - [ ] one file per endpoint row / Screen Index row — not per F-xx

package/scaffold/cursor/skills/ai-spector-generate-detail-design/SKILL.md

@@ -23,6 +23,7 @@ paths:
 ## Checklist
 
 ```
+- [ ] language confirmed (language-picker.md — check before first write)
 - [ ] graph validate; SRS + basic design present
 - [ ] generate-workflow waves + merge per target
 ```

package/scaffold/cursor/skills/ai-spector-generate-prototype/SKILL.md

@@ -2,9 +2,10 @@
 name: ai-spector-generate-prototype
 description: >-
   Generates static HTML/CSS/JS screen prototypes from basic-design screen specs and bundled UI themes.
-  Use when the user asks for HTML prototype, screen mockups, or prototype/src files. Asks user to
-  choose a theme if none is stored; uses stored preference on subsequent runs. Do not use for
-  markdown SRS/basic/detail design only, or graph operations without HTML output.
+  Use when the user asks for HTML prototype, screen mockups, or prototype/src files. When no theme is
+  stored, recommends 3 best-fit themes from project context, opens preview samples in the browser,
+  and waits for the user to choose before setup. Uses stored preference on subsequent runs. Do not use
+  for markdown SRS/basic/detail design only, or graph operations without HTML output.
 paths:
   - "prototype/**"
 ---
@@ -15,13 +16,18 @@ paths:
 
 ## Required reading
 
-[references/runbook.md](references/runbook.md) — theme resolution (no upfront picker), manifest, HTML rules.
+- [references/runbook.md](references/runbook.md) — manifest, HTML rules, theme resolution
+- [references/auth-picker.md](references/auth-picker.md) — **when no basic auth stored**: ask username/password, create htpasswd
+- [references/theme-picker.md](references/theme-picker.md) — **when no theme stored**: recommend 3, preview, confirm
 
 ## Checklist
 
 ```
+- [ ] language confirmed (language-picker.md — check before writing any screen text content)
 - [ ] list-screens + screen detail docs exist
-- [ ] theme resolved (request → theme.json → manifest → prototype.config.json → **ask user if none stored**)
+- [ ] basic auth resolved (config basicAuth + prototype/htpasswd → **auth picker if none**)
+- [ ] theme resolved (request → theme.json → manifest → config → **theme picker if none**)
+- [ ] if picker: 3 recommendations + previews opened + user confirmed before setup
 - [ ] prototype setup (with --theme when needed; persists when user named a theme)
 - [ ] one .html per screen; prototypeStem from manifest
 - [ ] prototype manifest && prototype validate --strict
@@ -31,4 +37,6 @@ paths:
 
 “HTML prototype”, “mockup screens”, “prototype with stripe theme” → this skill.
 
+“Help me pick a theme”, “what theme fits my app?”, “show me theme options” → [theme-picker.md](references/theme-picker.md) (even before generating).
+
 Constraints: `prototype/CLAUDE.md` in the project repo.

package/scaffold/cursor/skills/ai-spector-generate-prototype/references/auth-picker.md

@@ -0,0 +1,61 @@
+# Basic auth picker — username, password, htpasswd
+
+Before **any** prototype HTML is generated, the project must have HTTP basic auth configured. Run this flow when `prototype.config.json` has no `basicAuth` (or username/password is empty).
+
+Skip when:
+
+- `basicAuth.username` and `basicAuth.password` are already set in `.ai-spector/.docflow/config/prototype.config.json` — run `ai-spector prototype auth --from-config` only if `prototype/htpasswd` is missing
+- User is only previewing themes (no generation)
+
+## Step 1 — Check stored credentials
+
+Read `.ai-spector/.docflow/config/prototype.config.json`. If `basicAuth.username` and `basicAuth.password` are non-empty, skip asking. Ensure `prototype/htpasswd` exists; if not:
+
+```bash
+ai-spector prototype auth --from-config
+```
+
+## Step 2 — Ask the user
+
+Post exactly this message and **stop**. Do not run `prototype setup` or write HTML until the user replies.
+
+```
+Prototype hosting uses HTTP basic auth. Choose credentials for reviewers:
+
+  • **Username** (e.g. reviewer, demo, staging)
+  • **Password** (share securely with your team)
+
+Reply with both values (e.g. "username: demo / password: …").
+
+Credentials are saved in `.ai-spector/.docflow/config/prototype.config.json` and hashed into `prototype/htpasswd` for nginx/Apache.
+```
+
+If the user gives only one field, ask for the missing one and wait.
+
+## Step 3 — Persist and create htpasswd
+
+When both values are known, run (replace placeholders; never log the password in chat after this step):
+
+```bash
+ai-spector prototype auth --username <username> --password '<password>'
+```
+
+This writes:
+
+| Artifact | Purpose |
+|----------|---------|
+| `prototype.config.json` → `basicAuth` | Plain username/password for regeneration and team reference |
+| `prototype/htpasswd` | Apache apr1 hash for web server `auth_basic` |
+
+Then continue with theme resolution and [runbook.md](runbook.md) §1 (setup).
+
+## Changing credentials later
+
+If the user asks to rotate credentials:
+
+1. Collect new username/password (or reuse username with new password).
+2. Run `ai-spector prototype auth --username … --password …` again (overwrites config and htpasswd).
+
+## Security note
+
+`prototype.config.json` contains the password in plain text. Treat the file like a secret in production; restrict repo access or use environment-specific config outside git if needed.

package/scaffold/cursor/skills/ai-spector-generate-prototype/references/runbook.md

@@ -7,7 +7,8 @@ Generate **static HTML** prototypes from basic-design screen specs. All setup an
 ## Philosophy
 
 - **Screen design is source of truth** — `docs/basic-design/list-screens.md` + `docs/basic-design/screens/<slug>.md`
-- **Theme must be confirmed before generating** — if no theme is stored, ask the user to choose one before running setup. Once the user has chosen (stored in `prototype/theme.json` or `prototype.config.json`), never ask again.
+- **Basic auth must be configured before generating** — if `prototype.config.json` has no `basicAuth`, run the [auth picker](auth-picker.md): ask for username/password, then `ai-spector prototype auth`. Once saved, do not ask again unless the user wants to rotate credentials.
+- **Theme must be confirmed before generating** — if no theme is stored, run the [theme picker](theme-picker.md): recommend 3 fits from project context, open previews, wait for user choice. Once chosen (stored in `prototype/theme.json` or config), never ask again.
 - **One HTML per screen** — `prototype/src/<prototypeStem>.html` must match `prototype/manifest.json`
 - **Static only** — HTML/CSS/JS under `prototype/`; no frameworks, no CDN unless the theme DESIGN allows it
 
@@ -26,6 +27,16 @@ Generate **static HTML** prototypes from basic-design screen specs. All setup an
 
 ## Required behavior (agent runs CLI)
 
+### 0. Resolve basic auth
+
+**If `prototype.config.json` → `basicAuth` is missing** (no username/password), run the **[auth picker](auth-picker.md)** — do not generate HTML until credentials are saved and `prototype/htpasswd` exists.
+
+If credentials exist but `prototype/htpasswd` is missing:
+
+```bash
+ai-spector prototype auth --from-config
+```
+
 ### 1. Resolve theme and setup workspace
 
 **Resolution order** (first match wins):
@@ -35,14 +46,16 @@ Generate **static HTML** prototypes from basic-design screen specs. All setup an
 3. `prototype/manifest.json` → `themeName` (non-empty)
 4. `.ai-spector/.docflow/config/prototype.config.json` → `defaultTheme`
 
-**If no stored theme is found**, ask the user to choose before proceeding:
+**If no stored theme is found** and the user did **not** name one in this request, run the **[theme picker](theme-picker.md)** — do **not** ask a bare “which theme?” without recommendations.
 
-```
-No theme is saved yet. Which UI theme would you like for your prototype?
-Run `ai-spector prototype themes` to see all options, or name one (e.g. vercel, stripe, notion, linear.app).
-```
+Summary of the picker:
+
+1. Read project context (SRS, list-screens §1, knowledge, data-source).
+2. `ai-spector prototype themes --json` — pick **3 best-fit** themes with one-line rationale each.
+3. `ai-spector prototype preview <name> --open` for all 3 — user compares in the browser.
+4. Post a numbered table; **wait for user to choose** before setup.
 
-Wait for the user's answer — do **not** silently default to `vercel`. Once the user names a theme, proceed with setup; the choice is persisted and will not be asked again.
+Once the user confirms (or named a theme upfront), proceed with setup; the choice is persisted and will not be asked again.
 
 Setup (creates `prototype/`, copies `DESIGN.md`, seeds manifest when `list-screens.md` exists):
 
@@ -54,12 +67,18 @@ Omit `--theme` only when setup can infer the same name from stored files (the CL
 
 **Persist** when the user explicitly names a theme in this session: `prototype setup --theme <name>` updates `prototype/theme.json` and saves `defaultTheme` in `prototype.config.json` for later runs.
 
-List themes when the user asks (“what themes?”, “list prototype themes”):
+List all themes:
 
 ```bash
 ai-spector prototype themes
 ```
 
+Themes with a visual sample show `[preview]`. Open any theme sample:
+
+```bash
+ai-spector prototype preview <name> --open
+```
+
 ### 2. Plan screens
 
 ```bash
@@ -96,12 +115,15 @@ git commit -m "chore(prototype): add HTML screens (<theme>)"
 |-----------|--------|
 | “use stripe theme”, `--theme stripe` | `prototype setup --theme stripe` (persists preference); add `--force-design` if switching theme mid-branch |
 | “what themes?” | `ai-spector prototype themes` |
-| no theme in message, no stored theme | **Ask the user** to name a theme before proceeding |
+| “preview stripe theme”, “show me vercel theme” | `ai-spector prototype preview <name> --open` |
+| no theme in message, no stored theme | **[theme picker](theme-picker.md)**: recommend 3 → open previews → wait for choice |
 | no theme in message, stored theme found | Use stored theme — do not ask |
+| “help me pick a theme”, “which theme fits?” | Full [theme picker](theme-picker.md) even if not generating yet |
 
 ## Accuracy checklist
 
-- [ ] Theme resolved without blocking theme picker (unless user asked to list themes)
+- [ ] If no stored basic auth: [auth picker](auth-picker.md) run — username/password collected, `prototype auth` executed, `prototype/htpasswd` present
+- [ ] If no stored theme: [theme picker](theme-picker.md) run — 3 recommendations, previews opened, user confirmed
 - [ ] `prototype setup` run with resolved theme
 - [ ] Every generated file name matches `prototypeStem` in manifest
 - [ ] Wireframe/layout from screen detail doc reflected in HTML

package/scaffold/cursor/skills/ai-spector-generate-prototype/references/theme-picker.md

@@ -0,0 +1,118 @@
+# Theme picker — recommend, preview, confirm
+
+When **no theme is stored** and the user did **not** name one in this request, run this flow **before** `prototype setup`. Do not generate HTML until the user confirms a theme.
+
+Skip this flow when:
+
+- User named a theme (`--theme stripe`, “use notion theme”)
+- `prototype/theme.json`, manifest, or config already has a theme (use it — do not re-ask)
+- User is only asking to preview or list themes (no generation yet)
+
+## Step 1 — Gather project context
+
+Read enough to infer product type, audience, and visual tone. Prefer, in order:
+
+| Source | What to extract |
+|--------|-----------------|
+| `docs/basic-design/list-screens.md` §1 Design System | Stated palette, typography, density, light/dark |
+| `docs/srs/` (overview, use cases) | Domain (fintech, devtools, commerce, …), B2B vs consumer |
+| `.ai-spector/.docflow/analysis/knowledge.json` | Product name, features, actors |
+| `docs/data-source/` | Brand references, competitor mentions, industry |
+| User message | Explicit vibe (“dark dashboard”, “like Stripe”, “travel app”) |
+
+If context is thin, infer from screen names (e.g. checkout → commerce; admin dashboard → B2B SaaS).
+
+## Step 2 — Load theme catalog
+
+```bash
+ai-spector prototype themes --json
+```
+
+Each entry has `name`, `summary` (first line of SUMMARY.md), and `preview` (visual sample available).
+
+Optionally read `assets/themes/<name>/SUMMARY.md` for top candidates only — do not read all 65.
+
+## Step 3 — Pick 3 best-fit themes
+
+Choose **exactly 3** themes. Rank #1 = strongest match. Use signals below; tie-break with preview availability (`preview: true` preferred).
+
+### Domain → theme families
+
+| Project signal | Prefer (examples) |
+|----------------|-------------------|
+| Payments, banking, fintech, wallet | `stripe`, `wise`, `revolut`, `coinbase`, `kraken` |
+| Developer tools, infra, CI, APIs | `vercel`, `supabase`, `raycast`, `sentry`, `posthog`, `hashicorp` |
+| Issue tracking, eng productivity, dark UI | `linear.app`, `cursor`, `warp` |
+| Docs, wiki, workspace, notes | `notion`, `mintlify`, `miro` |
+| Spreadsheets, ops, internal tools | `airtable`, `clickhouse` |
+| E-commerce, merchant, checkout | `shopify`, `stripe` |
+| Marketplace, travel, consumer listings | `airbnb`, `uber` |
+| AI / ML product, chat, agents | `claude`, `mistral.ai`, `cohere`, `elevenlabs`, `x.ai`, `opencode.ai` |
+| Marketing site, landing, portfolio | `framer`, `webflow`, `lovable`, `resend` |
+| Scheduling, calendar | `cal` |
+| Support, messaging, CRM | `intercom`, `superhuman` |
+| Analytics, product data | `posthog`, `mixpanel-style` → `posthog`, `clickhouse` |
+| Automotive / luxury brand | `bmw`, `tesla`, `porsche-style` → `ferrari`, `lamborghini`, `bugatti` |
+| Media, social, content | `spotify`, `pinterest`, `wired`, `theverge` |
+| Enterprise / big tech tone | `ibm`, `meta`, `nvidia` |
+| Minimal / unknown | `vercel` (light dev), `notion` (friendly product), `linear.app` (dark pro) |
+
+### Tone modifiers
+
+| User / doc says | Lean toward |
+|-----------------|-------------|
+| Dark mode, dense dashboard | `linear.app`, `cursor`, `raycast`, `binance` |
+| Light, airy, friendly | `notion`, `airbnb`, `cal`, `lovable` |
+| Premium, polished, fintech | `stripe`, `wise`, `revolut` |
+| Playful, consumer | `spotify`, `airbnb`, `lovable` |
+| “Like X” | That theme if bundled; else closest row above |
+
+Write one sentence **why** for each of the 3 picks tied to **this project** (not generic theme marketing copy).
+
+## Step 4 — Show previews
+
+Open all 3 recommended themes in the browser so the user can compare:
+
+```bash
+ai-spector prototype preview <pick-1> --open
+ai-spector prototype preview <pick-2> --open
+ai-spector prototype preview <pick-3> --open
+```
+
+If a pick has no preview (`preview: false`), say so and still include it if it is the best domain match.
+
+## Step 5 — Present choices and wait
+
+Post a short message like this (adapt to project):
+
+```markdown
+No prototype theme is saved yet. Based on **[project/domain]**, here are 3 fits:
+
+| # | Theme | Why | Preview |
+|---|-------|-----|---------|
+| 1 | **stripe** | Fintech checkout + admin — matches your payment flows | opened in browser |
+| 2 | **wise** | Cross-border money — similar trust/minimal fintech tone | opened in browser |
+| 3 | **shopify** | Merchant commerce — if storefront is primary | opened in browser |
+
+Three preview tabs should be open. Reply with **1**, **2**, **3**, or another theme name (`ai-spector prototype themes` lists all).
+
+I will run setup after you choose.
+```
+
+**Stop here.** Do not run `prototype setup` or generate HTML until the user replies.
+
+## Step 6 — Persist choice
+
+When the user picks (number or name):
+
+```bash
+ai-spector prototype setup --theme <chosen-name>
+```
+
+Then continue the generate-prototype runbook (manifest → HTML → validate).
+
+If the user asks to see more options, run `prototype themes` and offer to preview additional names they shortlist.
+
+## User already named a theme
+
+If the user says “use stripe” or `--theme stripe`, skip the picker — run setup directly. Optionally offer a quick preview first only if they seem unsure (“want to preview before committing?”).

package/scaffold/cursor/skills/ai-spector-generate-srs/SKILL.md

@@ -23,6 +23,7 @@ paths:
 ## Checklist
 
 ```
+- [ ] language confirmed (language-picker.md — check before first write)
 - [ ] graph validate
 - [ ] runbook + generate-workflow followed
 - [ ] templates from .ai-spector/templates/srs/

package/scaffold/prototype/README.md

@@ -2,13 +2,34 @@
 
 Static HTML prototypes for screens defined in basic design.
 
+## Basic auth (once per project)
+
+Before generating HTML, configure HTTP basic auth (credentials in config, hash in htpasswd):
+
+```bash
+ai-spector prototype auth --username <user> --password '<secret>'
+```
+
+Stored in `.ai-spector/.docflow/config/prototype.config.json` (`basicAuth`) and `prototype/htpasswd`.
+
+Regenerate htpasswd after cloning if the file is missing:
+
+```bash
+ai-spector prototype auth --from-config
+```
+
 ## Setup (once per project or when changing theme)
 
-The agent resolves the theme automatically (`theme.json`, manifest, or `prototype.config.json` → `defaultTheme`). You only need to name a theme when you want to switch (e.g. “prototype with stripe theme”).
+The agent resolves the theme automatically (`theme.json`, manifest, or `prototype.config.json` → `defaultTheme`).
+
+**First time (no theme saved):** the agent reads your project docs, recommends **3 best-fit themes**, opens preview samples in your browser, and waits for you to pick before setup.
+
+You can also name a theme directly (e.g. “prototype with stripe theme”) to skip recommendations.
 
 ```bash
-ai-spector prototype setup --theme vercel   # persists defaultTheme when --theme is set
-ai-spector prototype themes                 # optional: list bundled themes
+ai-spector prototype themes                 # full list ([preview] = visual sample)
+ai-spector prototype preview stripe --open  # open one theme sample
+ai-spector prototype setup --theme vercel   # after you choose — persists defaultTheme
 ```
 
 ## Generate screens