@qnroa/qtype 0.0.2 → 0.0.4

package/docs/en/cli-reference.md

@@ -1,13 +1,12 @@
 # qtype CLI reference
 
-Chinese: [cli-reference.md](../zh/cli-reference.md)
+Chinese: [cli-reference.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/cli-reference.md)
 
-Brief overview of every top-level command. Run `qtype <cmd> --help`
-for full options.
+Brief per-command overview. Run `qtype <cmd> --help` for the full option list.
 
-## Global options
+## Global flags
 
-| Option | Description |
+| Flag | Notes |
 |---|---|
 | `-h, --help` | Show help |
 | `-v, --version` | Show version |
@@ -18,70 +17,109 @@ Language precedence: `--lang` > `$QTYPE_LANG` > `cli.lang` in
 
 ---
 
-## `qtype init [dir]`
+## `qtype init [path]`
 
-Scaffold a material repo in an existing directory. Alias for
-`qtype repo sync` with the same shape.
+Scaffold a material repo into an existing directory. Top-level alias for
+`qtype repo sync`.
 
 ```bash
-qtype init                    # in cwd
-qtype init my-deck --lang en  # in ./my-deck, English templates
+mkdir my-deck && qtype init my-deck --lang en
+qtype init                     # current directory
+qtype init my-deck --force     # overwrite qtype-managed spec files
+qtype init my-deck --dry-run   # print the plan, no writes
 ```
 
 Creates: `QTYPE.md` (authoring spec), `AGENTS.md` / `CLAUDE.md` /
 `GEMINI.md` (symlinks to `QTYPE.md`), `README.md`, `TODO.md`,
-`index.md`, `log.md`, `material/` with an example, `.qtype/`
-skeleton.
+`index.md`, `log.md`, one starter per material type at
+`material/{word,sentence,article,snippet,qa,code}.md` + accompanying
+SVG images under `material/assets/<type>/`, and a `.qtype/` skeleton.
 
-Idempotent — skips existing user content, overwrites managed spec
-files only with `--force`.
+Idempotent — user content is left alone; only `--force` overwrites
+qtype-managed spec files.
 
 ---
 
 ## `qtype repo new <name>`
 
-Create a fresh material repo directory.
+Create a fresh material-repo directory under the parent.
 
 ```bash
-qtype repo new my-deck --lang zh
-cd my-deck
+qtype repo new my-deck --lang en
+qtype repo new my-deck --description "GRE vocab" --git
 ```
 
-## `qtype repo sync [dir]`
+| Flag | Notes |
+|---|---|
+| `--lang <zh\|en>` | Template language |
+| `--description <text>` | One-liner for README |
+| `--dir <path>` | Parent directory (default: cwd) |
+| `--git` | Also `git init` |
+
+## `qtype repo sync [path]`
+
+Bring an existing repo up to spec. Same as `qtype init`.
+
+---
+
+## `qtype check [path]`
 
-Fill in conventions in an existing repo. Same as `qtype init`.
+Top-level alias for `qtype content lint`. Reports cards containing
+characters the typing engine can't handle. Non-zero exit code for CI.
+
+```bash
+qtype check                    # cwd
+qtype check --json             # JSON output for tooling
+```
 
 ---
 
-## `qtype check [dir]`
+## `qtype content lint | validate | search`
+
+- `lint` — text-level card validation (untypable chars → error)
+- `validate` — schema-level validation (frontmatter field types)
+- `search <query>` — full-text substring search across cards
 
-Validate every card in `material/*.md`. Reports cards containing
-characters the typing engine can't handle (returns non-zero exit).
-Read-only; drop it into CI before `publish build`.
+`search` supports filters + structured output:
 
 ```bash
-qtype check
+qtype content search "closure"
+qtype content search "apple" --tag GRE --type word --limit 5
+qtype content search "*" --tag math --json    # scriptable
 ```
 
+| `search` flag | Notes |
+|---|---|
+| `--limit <n>` | Max results (default 20) |
+| `--tag <tag...>` | Filter by tag (repeatable; AND semantics) |
+| `--type <type...>` | Filter by material type (repeatable) |
+| `--json` | Emit JSON results |
+
 ---
 
-## `qtype publish build [dir]`
+## `qtype publish build [path]`
 
-Assemble the static site into `dist/`. Runs:
+Assemble a static site under `<repo>/dist/`. Steps:
 
 1. Parse every `material/*.md`
-2. Pre-render Mermaid diagrams (unless `publish.mermaid=off`)
-3. Encrypt materials (if `publish.password.enabled=true`)
-4. Emit per-material HTML + `_data/material.json`
-5. Copy the pre-built view bundle into `dist/_app/`
+2. Pre-render Mermaid diagrams (unless `publish.mermaid=off`); emits
+   `dist/material/mermaid.json` + `mermaid.css` (dark + light SVGs)
+3. Encrypt material (if `publish.password.enabled=true`) — argon2id
+   derives an AES-256 key, AES-GCM encrypts each material, output
+   `<file>.enc.json`
+4. Emit `dist/material/index.json` manifest (browser lazy-loads from it)
+5. Copy the pre-built view bundle into `dist/` root — the whole dir is
+   deployable to any static host
 
 ```bash
 qtype publish build
+QTYPE_PUBLISH_PASSWORD=demo qtype publish build   # non-interactive
+qtype publish build --out ./build                 # custom output dir
 ```
 
-## `qtype publish serve [dir]`
+## `qtype publish serve [path]`
 
-Local HTTP preview of `dist/`. Defaults to port 4000.
+Local HTTP preview of `dist/`. Default port 4000.
 
 ```bash
 qtype publish serve
@@ -90,26 +128,40 @@ qtype publish serve --port 8080
 
 ## `qtype publish init`
 
-Write `.gitignore` + a GitHub Pages workflow so pushing to `main`
-triggers a build + deploy.
+Write deployment helpers. **By default only writes `.gitignore`**;
+`--ci github` also drops `.github/workflows/pages.yml` so pushing to
+`main` triggers build + deploy.
+
+```bash
+qtype publish init                # gitignore only
+qtype publish init --ci github    # with GitHub Pages deploy
+```
 
 ## `qtype publish password set / clear / status`
 
-Password-protection lifecycle. `set` prompts for a password, derives
-an AES key via Argon2id, and stores the resulting salt + hash in
-`.qtype/config.json`. `clear` disables protection.
+Password protection lifecycle. `set` prompts, then uses Argon2id
+(64 MiB / t=3 / p=1) to derive a transient AES key and stores the
+hash + salt in `.qtype/config.json`. The **password itself is never
+stored**; every `publish build` re-derives the AES key from the
+supplied password.
 
 ```bash
-qtype publish password set
+qtype publish password set        # interactive
+echo "hunter2" | qtype publish password set   # stdin, scriptable
 qtype publish password status
+qtype publish password clear
 ```
 
+Browser side: the reader's `PasswordGate` runs the same argon2id
+derivation and caches the resulting AES key in `sessionStorage` — a
+reload in the same tab doesn't re-prompt.
+
 ---
 
 ## `qtype pack [-o file]`
 
-Bundle the current material repo into a `.tar.gz`. Ignores `dist/`,
-`node_modules/`, `.git/`, and any pre-existing tarball.
+Bundle the current material repo into a `.tar.gz`. Skips `dist/`,
+`node_modules/`, `.git/`, and any pre-existing tarballs.
 
 ```bash
 qtype pack -o my-deck.tar.gz
@@ -117,51 +169,37 @@ qtype pack -o my-deck.tar.gz
 
 ---
 
-## `qtype content lint | validate | search`
-
-- `lint` — style-level pass over material files
-- `validate` — schema-level pass; complements `qtype check`
-- `search <query>` — plain substring search across cards
-
-```bash
-qtype content search "closure"
-```
-
----
-
 ## `qtype config get / set / unset / list`
 
-Git-style two-layer configuration (user layer in
-`~/.config/qtype/config.json`, repo layer in `<repo>/.qtype/config.json`).
+Two-layer, git-style config (user layer at
+`~/.config/qtype/config.json`, repo layer at
+`<repo>/.qtype/config.json`).
 
-Read precedence: repo > user > schema default. Writes default to
-repo when the key is a repo-scope key, user when user-only, and
-prefer repo when both.
+Read precedence: **CLI flag > repo > user > schema default**. Write
+defaults route repo-only keys to repo, user-only to user, dual-scope
+keys prefer repo when available.
 
 ```bash
-qtype config set cli.lang zh --global
+qtype config set cli.lang en --global
 qtype config set typing.theme mocha
 qtype config get typing.theme --show-origin
 qtype config list
 qtype config unset typing.targetWpm
 ```
 
-Known keys include:
-
-- `cli.lang`, `cli.color` (user-only)
-- `repo.name`, `publish.password.*` (repo-only)
-- `repo.lang`, `typing.theme`, `typing.targetWpm`, `typing.tabBehavior`,
-  `typing.hint`, `typing.showKeyboard`, `typing.showHands`,
-  `publish.mermaid` (both scopes)
-
-Strict mode: unknown keys are rejected.
-
----
+**Known keys**:
 
-## `qtype plugin`
+- **User-only**: `cli.lang`, `cli.color`
+- **Repo-only**: `repo.name`, `publish.password.enabled`,
+  `publish.password.hash`, `publish.password.aesSalt`,
+  `publish.password.scope`, `publish.password.selected`
+- **Dual-scope**: `repo.lang`, `typing.theme`, `typing.targetWpm`,
+  `typing.tabBehavior`, `typing.hint`, `typing.showKeyboard`,
+  `typing.showHands`, `publish.mermaid`
 
-Command skeleton. Runtime execution not implemented yet — see
-[TODO.md](../../TODO.md).
+Strict mode: unknown keys are rejected. View-side UI settings
+(auto-speak / math renderer / AFK threshold / …) live in a
+**browser-side kv store**, not this config.
 
 ---
 

package/docs/en/deployment.md

@@ -0,0 +1,183 @@
+# Deployment
+
+Chinese: [deployment.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/deployment.md)
+
+`qtype publish build` emits a plain static `dist/`: HTML + JS + CSS +
+`material/*.md` (or encrypted `.enc.json`) + assets. **No server side**
+— it drops onto any CDN / static host.
+
+## Pre-flight checklist
+
+```bash
+qtype check                # lints clean?
+qtype publish build        # emits dist/
+ls dist/                   # index.html + assets/ + material/ expected
+```
+
+**Key detail**: your output is `dist/`, not `dist/view/`. The former is
+your user repo's build output; the latter is the dev-time view bundle
+cache — `publish build` copies `dist/view/*` into your `dist/`.
+
+## GitHub Pages
+
+qtype ships a one-liner workflow:
+
+```bash
+qtype publish init --ci github
+```
+
+Writes `.github/workflows/pages.yml`. Pushing to `main`:
+1. `npm install -g @qnroa/qtype`
+2. `qtype publish build`
+3. Uploads `dist/` to GitHub Pages
+
+**In your GitHub repo settings**:
+- Settings → Pages → Source: **GitHub Actions**
+
+**If password-protected**, inject the password as a secret:
+
+```yaml
+- run: qtype publish build
+  env:
+    QTYPE_PUBLISH_PASSWORD: ${{ secrets.QTYPE_PASSWORD }}
+```
+
+Add a secret named `QTYPE_PASSWORD` under Settings → Secrets and
+variables → Actions.
+
+## Cloudflare Pages
+
+1. Cloudflare Dashboard → Pages → Create → Connect Git
+2. Build config:
+   - **Framework preset**: `None`
+   - **Build command**: `npx @qnroa/qtype publish build`
+   - **Build output directory**: `dist`
+   - **Node version**: `20` (env `NODE_VERSION=20`)
+3. Password: Settings → Environment variables → add
+   `QTYPE_PUBLISH_PASSWORD` (Production scope, Encrypted).
+
+## Vercel
+
+`vercel.json` at repo root:
+
+```json
+{
+  "buildCommand": "npx @qnroa/qtype publish build",
+  "outputDirectory": "dist",
+  "framework": null
+}
+```
+
+Add the password via `vercel env add QTYPE_PUBLISH_PASSWORD`.
+
+## Netlify
+
+`netlify.toml` at repo root:
+
+```toml
+[build]
+  command = "npx @qnroa/qtype publish build"
+  publish = "dist"
+
+[build.environment]
+  NODE_VERSION = "20"
+```
+
+Password: Site settings → Environment variables.
+
+## Self-hosted nginx
+
+After `qtype publish build`:
+
+```bash
+scp -r dist/* user@yourhost:/var/www/your-site/
+```
+
+nginx config:
+
+```nginx
+server {
+    listen 80;
+    server_name your-site.example;
+    root /var/www/your-site;
+    index index.html;
+
+    # SPA fallback: any route that isn't a real file goes to
+    # index.html, so client-side routing (/typing/xxx.md etc.) works.
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Static assets are content-hashed, safe to cache aggressively.
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # Materials might be re-published — keep the cache short.
+    location /material/ {
+        expires 5m;
+    }
+}
+```
+
+Enable gzip:
+
+```nginx
+gzip on;
+gzip_types text/plain text/css application/javascript application/json image/svg+xml;
+gzip_min_length 1024;
+```
+
+## Docker
+
+Minimal Dockerfile — build + serve:
+
+```dockerfile
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY . .
+RUN npm install -g @qnroa/qtype && qtype publish build
+
+FROM nginx:alpine
+COPY --from=build /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+```
+
+`nginx.conf` is the SPA-fallback config from the previous section.
+
+## Password-protected deploys
+
+Password protection is **client-side decryption** — the server only
+serves encrypted `.enc.json`; the browser decrypts locally after the
+user types the password. So:
+
+- ✅ **Server needs no auth** — the encrypted content itself is the
+  protection.
+- ✅ Public GitHub Pages / Cloudflare Pages are fine.
+- ⚠️ **Attackers can download the whole dist** and brute-force the KDF
+  offline. argon2id at 64 MiB / t=3 / p=1 pins each guess at ~700ms,
+  but that isn't infinite strength. **Don't use weak passwords** (any
+  short dictionary word/phrase).
+- ⚠️ Bad passwords can't be detected server-side — no server-side
+  rate limiting exists. The view has a *local* limiter (2 / 5 / 15s
+  cooldown after 3 fails) that protects against typos, not attacks.
+
+## Sub-path deploys
+
+If your site lives at `https://example.com/mydeck/` rather than the
+root, that's **not supported today** — the client hardcodes fetches
+against `/material/*`. Either deploy at the root, or use a reverse
+proxy to rewrite `/mydeck/*` → `/*`.
+
+## Verifying the deploy
+
+Open:
+- `/` → material list (password prompt first if encrypted)
+- `/material/index.json` → JSON manifest
+- DevTools → Network should show:
+  - one `/material/index.json`
+  - one `/material/<file>.md` (or `.enc.json`) per card you open
+  - images from `/material/assets/**/*.svg`
+
+**Any 404** = missing SPA fallback or wrong path prefix.

package/docs/en/getting-started.md

@@ -0,0 +1,112 @@
+# Getting started
+
+Chinese: [getting-started.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/zh/getting-started.md)
+
+## 0. Prereqs
+
+- Node ≥ 20
+- A terminal
+
+## 1. Create a repo
+
+```bash
+mkdir my-deck
+npx @qnroa/qtype init my-deck --lang en
+cd my-deck
+```
+
+`qtype init` drops into `my-deck/`:
+
+- `QTYPE.md` — authoring spec (for you and for LLM agents)
+- `material/word.md`, `sentence.md`, `article.md`, `snippet.md`, `qa.md`, `code.md` — one starter per material type, each a working demo
+- `material/assets/<type>/*.svg` — the SVGs the starters reference
+- `README.md`, `TODO.md`, `index.md`, `log.md` — empty scaffolds
+- `.qtype/config.json` — repo-level config
+
+**Key idea**: one `.md` file = one deck; the whole file has a single
+`type`.
+
+## 2. Peek at a starter
+
+`material/sentence.md`:
+
+```markdown
+---
+title: Sentence example
+type: sentence
+tags: [example, sentence]
+---
+
+# The quick brown fox jumps over the lazy dog.
+## /ðə kwɪk braʊn fɑks/
+### The classic English pangram — every letter A–Z appears once.
+#### ![A-Z](./assets/sentence/pangram.svg)
+
+# Practice makes perfect.
+### With enough practice, anything becomes easy.
+```
+
+- **H1 (`#`) = typing target** (what you type)
+- H2 phonetic / H3 gloss / H4 image are optional annotation slots
+
+Each type has its own shape — full reference in
+[material-types.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/material-types.md); a shorter overview lives in
+[authoring.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/authoring.md).
+
+## 3. Validate
+
+```bash
+npx @qnroa/qtype check
+```
+
+Read-only lint: flags characters the typing engine can't handle
+(emoji / zero-width / etc.). **Exit code 0 = clean.**
+
+## 4. Build + preview
+
+```bash
+npx @qnroa/qtype publish build      # emits dist/
+npx @qnroa/qtype publish serve      # http://localhost:4000
+```
+
+Open the URL — you'll see the 6 materials on the home page; click any
+to start typing.
+
+## 5. Deploy
+
+Fastest route is GitHub Pages:
+
+```bash
+npx @qnroa/qtype publish init --ci github
+git init && git add . && git commit -m "init"
+git remote add origin https://github.com/YOUR_NAME/my-deck.git
+git push -u origin main
+```
+
+In your repo Settings → Pages → set Source to **GitHub Actions**.
+The workflow will publish on push.
+
+Other targets (Cloudflare / Vercel / Netlify / nginx) →
+[deployment.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/deployment.md).
+
+## 6. Optional: encrypt the site
+
+```bash
+npx @qnroa/qtype publish password set
+# type a password interactively
+
+npx @qnroa/qtype publish build
+```
+
+Visitors now see a password gate; content is AES-256-GCM encrypted
+client-side.
+
+## Next steps
+
+- Add more decks → copy any starter, rename, edit
+- Ask an LLM to author for you → point Claude / Copilot at `QTYPE.md`
+  and say "author a GRE vocab deck following this spec"
+- Tune the reader UX → gear icon (bottom right) or [settings.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/settings.md)
+- Tune typing rules (strict / lenient / case-insensitive) →
+  [typing-rules.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/typing-rules.md)
+- Keyboard shortcuts → [shortcuts.md](https://www.npmjs.com/package/@qnroa/qtype?activeTab=code&filepath=docs/en/shortcuts.md)