Add documentation links to README and include 'docs' directory in package.json

Author: alexy-os

README.md

@@ -4,6 +4,15 @@ Universal **shadcn-style** registry service: `init` / `add` / `list` / `diff` /
 
 Contract version: **2.0.0**
 
+**Full documentation (English):** [docs/README.md](./docs/README.md)
+
+| Start here | |
+|------------|--|
+| [Getting started](./docs/getting-started.md) | Install + first init/add |
+| [Commands](./docs/commands.md) | Complete CLI reference |
+| [Scenarios](./docs/scenarios/) | React, Svelte, Templ, private CDN, publish, CI |
+| [Registry format](./docs/registry-format.md) | Item / index JSON contract |
+
 ## Idea
 
 ```text
@@ -174,6 +183,8 @@ npm run pack:check   # dry-run tarball contents
 
 Maintainer scripts (local fixtures, CDN probe): see [scripts/README.md](scripts/README.md).
 
+User & author guides: see [docs/README.md](docs/README.md).
+
 ## License
 
 MIT

docs/README.md

@@ -0,0 +1,59 @@
+# ui8kit CLI documentation
+
+Contract **2.0.0** · Node.js `>=20`
+
+`ui8kit` is a **file-based registry CLI** (shadcn-style): it fetches registry items from a CDN (or local server) and **writes source files into your app**. It does not treat `node_modules` as the kit source of truth, so Tailwind and bundlers see real classes and files.
+
+This docs set covers concepts, configuration, every command, the registry JSON contract, CDN/cache behavior, publishing, end-to-end scenarios, troubleshooting, and migration from v1.
+
+## Guides
+
+| Doc | Contents |
+|-----|----------|
+| [Getting started](./getting-started.md) | Install, first `init` / `add`, verification |
+| [Concepts](./concepts.md) | Mental model, folders, types, runtimes, path remap |
+| [Configuration](./configuration.md) | Full `ui8kit.config.json` reference |
+| [Commands](./commands.md) | Every command, flag, and example |
+| [Registry format](./registry-format.md) | Item / index JSON contract |
+| [CDN and cache](./cdn-and-cache.md) | URL resolution, pinning, offline cache |
+| [Publishing a registry](./publishing.md) | `scan` → `build` → host `/r` |
+| [Troubleshooting](./troubleshooting.md) | Common failures and fixes |
+| [Migration v1 → v2](./migration-v2.md) | Breaking changes checklist |
+
+## Scenarios
+
+| Scenario | Audience |
+|----------|----------|
+| [Consumer app (React)](./scenarios/consumer-react.md) | App teams installing primitives |
+| [Svelte / Solid / Vue](./scenarios/multi-runtime.md) | Multi-runtime digests |
+| [Go Templ / PHP](./scenarios/non-js.md) | Kit on disk without a JS framework |
+| [Private / strict CDN](./scenarios/private-cdn.md) | Locked registry URL + version pin |
+| [Maintain & publish registry](./scenarios/maintain-registry.md) | Authors assembling `packages/registry/r` |
+| [CI dry-run & upgrades](./scenarios/ci-and-upgrades.md) | Automation, `diff`, force updates |
+
+## Quick mental model
+
+```text
+                    ┌─────────────────────┐
+                    │  Registry CDN `/r`  │
+                    │  index.json + items │
+                    └──────────┬──────────┘
+                               │  fetch
+                               ▼
+┌──────────────┐    ui8kit add     ┌────────────────────────┐
+│ App project  │ ◄──────────────── │ files under {dir}/…    │
+│ ui8kit.config│                   │ components/ui, utils…  │
+└──────────────┘                   └────────────────────────┘
+```
+
+Authors use the reverse path:
+
+```text
+source kit  →  ui8kit scan  →  registry.json  →  ui8kit build  →  packages/registry/r
+```
+
+## Related
+
+- Package README: [../README.md](../README.md)
+- Maintainer scripts: [../scripts/README.md](../scripts/README.md)
+- Changelog: [../CHANGELOG.md](../CHANGELOG.md)

docs/cdn-and-cache.md

@@ -0,0 +1,91 @@
+# CDN and cache
+
+## Registry base URL
+
+A **base** is a URL that already points at the `/r` tree (no trailing slash required):
+
+```text
+https://cdn.example.com/ui8kit/r
+https://unpkg.com/@ui8kit/registry@latest/r
+http://127.0.0.1:4173/r
+```
+
+From that base the CLI requests:
+
+```text
+{base}/index.json
+{base}/components/ui/button.json
+{base}/utils/cn.json
+…
+```
+
+## Resolution order
+
+`getCdnUrls` builds an ordered unique list:
+
+1. Explicit `--registry-url` / `config.registryUrl` (after version rewrite)
+2. If **not** (`strictCdn` **and** explicit URL): append  
+   - `config.cdnBaseUrls` when set, else  
+   - built-in defaults:
+
+```text
+https://unpkg.com/@ui8kit/registry@latest/r
+https://cdn.jsdelivr.net/npm/@ui8kit/registry@latest/r
+https://raw.githubusercontent.com/ui8kit/core/refs/heads/main/packages/registry/r
+```
+
+### Strict mode
+
+```bash
+ui8kit add button --registry-url https://cdn.example.com/r --strict-cdn
+```
+
+Only that URL is tried. Failures do **not** fall back to public CDNs. Prefer this for private registries and CI.
+
+### Version pinning
+
+`--registry-version 0.1.0` / `registryVersion` rewrites `@latest` in URL templates:
+
+```text
+…/@ui8kit/registry@latest/r  →  …/@ui8kit/registry@0.1.0/r
+```
+
+Custom hosts without `@latest` are left unchanged; pin by changing the path yourself or hosting immutable digests.
+
+## Inspect resolution
+
+```bash
+ui8kit info --cdn
+ui8kit info --json
+```
+
+Maintainer probe (repo scripts, not shipped in tarball logic):
+
+```bash
+npm run get-cdn
+node scripts/get-cdn.js --url https://cdn.example.com/r --path index.json --json
+```
+
+## Local cache
+
+Successful JSON responses are cached under:
+
+```text
+~/.ui8kit/cache/
+```
+
+- Default TTL: **1 hour**
+- Bypass: `ui8kit --no-cache …` or clear with `ui8kit cache clear`
+- `reset --with-cache` also clears the cache
+
+Cache keys are derived from request paths; safe to delete anytime.
+
+## Offline / air-gapped
+
+1. Host `packages/registry/r` on an internal static server  
+2. Set `registryUrl` + `strictCdn: true`  
+3. Optionally pre-warm: run `list` / `add` once on a builder image and ship the cache (usually unnecessary if the internal CDN is fast)
+
+## Retry
+
+`ui8kit add … --retry` increases fetch retries for flaky CDNs. Prefer fixing CDN reliability for production CI.