From 8837bdfa2a90a0bd2686c1a106b175842e4a1052 Mon Sep 17 00:00:00 2001
From: Arnav Goel <arnavgoel2@gmail.com>
Date: Thu, 30 Apr 2026 21:10:39 -0400
Subject: [PATCH] docs: rewrite auth, add quickstart + recipes + demo upload
 playbook

- docs/authentication.md: rewrite around user-scoped API keys (the actual
  shipped auth model) instead of the legacy admin JWT impersonation flow;
  add hosted-docs link and dashboard walkthrough GIF.
- docs/quickstart.md: zero-to-search walkthrough with placeholder IDs and
  expected output, referenced from the README.
- docs/recipes.md: bulk ingest, piping, scripting, and CI patterns.
- .github/UPLOAD_DEMO_VIDEO.md: playbook for uploading the demo MP4 to
  GitHub user-attachments so the README can embed it inline.
---
 .github/UPLOAD_DEMO_VIDEO.md |  62 ++++++++++
 docs/authentication.md       | 202 ++++++++++++++++++--------------
 docs/quickstart.md           | 217 +++++++++++++++++++++++++++++++++++
 docs/recipes.md              | 211 ++++++++++++++++++++++++++++++++++
 4 files changed, 603 insertions(+), 89 deletions(-)
 create mode 100644 .github/UPLOAD_DEMO_VIDEO.md
 create mode 100644 docs/quickstart.md
 create mode 100644 docs/recipes.md

diff --git a/.github/UPLOAD_DEMO_VIDEO.md b/.github/UPLOAD_DEMO_VIDEO.md
new file mode 100644
index 0000000..446adcf
--- /dev/null
+++ b/.github/UPLOAD_DEMO_VIDEO.md
@@ -0,0 +1,62 @@
+# Uploading the kscli demo video
+
+The hero video in `README.md` is served from **GitHub's user-attachments CDN** — the same storage backend that powers drag-and-drop uploads in issues and PRs. That URL is backed by GitHub, cached globally, costs nothing, does not bloat the repo, and renders inline on every `README.md` view on github.com.
+
+This document is the playbook for replacing the placeholder video URL after the Remotion render completes.
+
+## Why user-attachments and not something else?
+
+| Option | Renders inline on github.com? | Repo bloat? | CDN-backed? | Effort |
+|---|---|---|---|---|
+| **`user-attachments` URL in `<video>` tag** ✅ | Yes | None | Yes (GitHub) | One-time upload |
+| `<img>` GIF from external CDN | Yes (as GIF, not a real video) | None | Depends | Medium |
+| `<video>` with raw.githubusercontent.com path | Partial (depends on size) | Yes (MP4 in repo) | Yes | Low |
+| GitHub Release asset | Not inline | No | Yes | Medium |
+| External `<video>` URL (S3, Cloudflare, etc.) | **No** — GitHub sanitizes cross-origin video src | None | Varies | High |
+
+GitHub's README renderer only allows HTML5 `<video>` tags whose `src` points at `github.com/user-attachments/assets/...` or a raw file inside the same repo. Anything else is stripped. That makes `user-attachments` the correct answer.
+
+## How to upload
+
+**You need:** the final `kscli-demo.mp4` from the Remotion render (spec: [ks-marketing/content/2026-04-15-ks-cli-demo-video/brief.md](../../ks-marketing/content/2026-04-15-ks-cli-demo-video/brief.md)).
+
+**Target format:** H.264 MP4, 1920×1080 @ 30fps, ~45 seconds, under 10 MB (user-attachments hard cap is 10 MB per file — tune the Remotion render bitrate if you're over).
+
+### Step-by-step
+
+1. Go to [github.com/knowledgestack/ks-cli/issues/new](https://github.com/knowledgestack/ks-cli/issues/new).
+2. In the issue body, **drag `kscli-demo.mp4` directly into the text area** (or paste it from the clipboard).
+3. GitHub uploads the file and rewrites it in-place to a markdown image link like:
+   ```
+   ![kscli-demo](https://github.com/user-attachments/assets/3f1b2c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d)
+   ```
+4. **Copy the URL** — only the `https://github.com/user-attachments/assets/<uuid>` part, without the markdown syntax.
+5. **Do not submit the issue.** Close the draft (the URL stays live even if the issue is never created — user-attachments are not tied to issue lifecycle).
+6. Open `README.md` and find the `HERO MEDIA` HTML comment block. The README currently has **two blocks**:
+    - an active `<a><img></a>` fallback that shows a clickable poster
+    - a commented-out `<video>` block marked *"once the Remotion MP4 is uploaded..."*
+
+   **Swap them:**
+    - Delete the active `<a><img></a>` block.
+    - Uncomment the `<video>` block (remove the wrapping `<!--` / `-->`).
+    - Paste the copied URL in place of `PASTE-UUID-HERE` on the `src` attribute.
+7. Do the same swap in `ks-docs/cli/index.mdx` — it has the same two blocks inside `{/* ... */}` MDX comments.
+8. Commit and open a PR against both repos titled `docs: wire up demo video`.
+
+### One-liner sanity check
+
+Before pushing, preview the `<video>` tag renders correctly by pasting the full `<video ...>` block into a **new** issue body on the same repo. If it plays in the preview pane, it will play in the README.
+
+## Updating the poster frame
+
+The `<video>` tag also references a `poster=` image (shown before the user hits play). The render pipeline outputs `hero-poster.png` alongside the MP4 — upload it using the same drag-and-drop trick, or publish it to `docs.knowledgestack.ai/assets/kscli/hero-poster.png` via the ks-docs deploy (see [ks-docs cli section](../../ks-docs/cli/index.mdx)).
+
+## Rotating or removing the video
+
+user-attachments URLs never expire and are not revocable individually. To change the video, upload a new one and replace the URL — the old asset stays on GitHub's CDN but is no longer referenced.
+
+## Related
+
+- [README.md](../README.md) — the actual embed
+- [ks-marketing brief](../../ks-marketing/content/2026-04-15-ks-cli-demo-video/brief.md) — the Remotion video spec
+- [Mintlify cli/index.mdx](../../ks-docs/cli/index.mdx) — the same video embedded in the hosted docs site
diff --git a/docs/authentication.md b/docs/authentication.md
index b3bdf6c..61ef9e0 100644
--- a/docs/authentication.md
+++ b/docs/authentication.md
@@ -1,141 +1,146 @@
 # Authentication
 
-kscli uses JWT-based authentication via admin impersonation. An admin API key is used to obtain a short-lived JWT token for a specific user/tenant pair, and the token is cached locally for reuse.
+> 📚 **Hosted version:** [docs.knowledgestack.ai/kscli/authentication](https://docs.knowledgestack.ai/kscli/authentication) — same page with inline video of the dashboard flow.
 
-## Auth Flow
+<p align="center">
+  <img src="https://docs.knowledgestack.ai/assets/kscli/api-key-walkthrough.gif"
+       alt="Create API key → kscli login → whoami"
+       width="720" />
+</p>
 
-```
-                                 ┌──────────────┐
-  kscli assume-user              │  ks-backend  │
-  --tenant-id T                  │              │
-  --user-id U       ──────────>  │ POST         │
-                    X-Admin-     │ /v1/auth/    │
-                    Api-Key      │ assume_user  │
-                                 └──────┬───────┘
-                                        │ { "token": "<jwt>" }
-                                        v
-                              ┌─────────────────────┐
-                              │ ~/.credentials file │
-                              │ (0600 permissions)  │
-                              │                     │
-                              │ token, user_id,     │
-                              │ tenant_id,          │
-                              │ expires_at,         │
-                              │ admin_api_key       │
-                              └─────────┬───────────┘
-                                        │
-                    subsequent commands  │  auto-loaded
-                                        v
-                              ┌─────────────────────┐
-                              │  ksapi.ApiClient    │
-                              │  cookie: ks_uat=JWT │
-                              └─────────────────────┘
-```
-
-## Commands
+`kscli` authenticates with a **user-scoped API key**. No admin impersonation, no JWT dance — the key is presented as a bearer token on every request and carries the permissions of the user that created it.
 
-### `assume-user`
-
-Authenticates as a specific user in a specific tenant.
+## TL;DR
 
 ```bash
-kscli assume-user --tenant-id <tenant-uuid> --user-id <user-uuid>
+# 1. Create a key in the dashboard → copy it once
+# 2. Log in
+kscli login --api-key sk-user-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
+# 3. Confirm
+kscli whoami
 ```
 
-**What it does** (`src/kscli/commands/auth.py:19-25`):
+## How to create an API key
+
+API keys are created from the Knowledge Stack dashboard.
 
-1. Reads `ADMIN_API_KEY` from env or config (`src/kscli/config.py:33-42`)
-2. Sends `POST /v1/auth/assume_user` with `X-Admin-Api-Key` header (`src/kscli/auth.py:26-34`)
-3. Decodes the JWT (without verification) to extract the expiration claim (`src/kscli/auth.py:43`)
-4. Writes the credentials file with `0600` permissions (`src/kscli/auth.py:46-57`)
+1. Sign in to **[app.knowledgestack.ai](https://app.knowledgestack.ai)**. New users can sign up with email/password or Google SSO.
+2. Open the avatar menu (top-right) → **My Account**.
+3. Click the **API Keys** tab.
+4. Click **Create API key**.
+5. Give the key a descriptive label (e.g. `kscli on my laptop`, `CI pipeline`, `ingest cron`) so you can audit and revoke it later.
+6. **Copy the key immediately.** Keys are shown exactly once, and `kscli` needs the full `sk-user-...` string.
+7. (Optional) Set an expiry if the dashboard offers one.
 
-**Output:**
+Revoke a key from the same page when you rotate credentials or when a laptop is lost. Revocation is immediate — the next `kscli` command from that machine will exit with code `2` and prompt you to log in again.
+
+## Auth flow
 
 ```
-Authenticated as user 00000000-... in tenant 00000000-...
-Token expires: 2026-02-23T12:00:00+00:00
+  ┌──────────┐    kscli login            ┌──────────────┐
+  │  user    │  --api-key sk-user-...    │  ks-backend  │
+  │          │  ──────────────────────>  │              │
+  │          │    GET /users/me          │  validates   │
+  │          │    Authorization: Bearer  │  and returns │
+  │          │  <──────────────────────  │  200 + user  │
+  └──────────┘                           └──────────────┘
+       │
+       │  on success
+       v
+  ┌──────────────────────────────┐
+  │ /tmp/kscli/.credentials      │  mode 0600
+  │ {"api_key": "sk-user-..."}   │
+  └──────────────────────────────┘
+  ┌──────────────────────────────┐
+  │ ~/.config/kscli/config.json  │
+  │ {"base_url": "...",          │
+  │  "verify_ssl": true}         │
+  └──────────────────────────────┘
 ```
 
-### `whoami`
+Implementation: [`src/kscli/commands/auth.py`](../src/kscli/commands/auth.py), [`src/kscli/auth.py`](../src/kscli/auth.py), [`src/kscli/client.py`](../src/kscli/client.py).
+
+## Commands
 
-Shows the currently authenticated identity by calling the `/users/me` API endpoint.
+### `login`
 
 ```bash
-kscli whoami
+kscli login --api-key <key>                          # prompts if --api-key omitted
+kscli login --api-key <key> --url http://localhost:8000
 ```
 
-**Output** (table format):
+Validates the key with `GET /users/me` before writing it to disk. If validation fails, nothing is persisted.
 
-```
-┌─────────────┬──────────────────────────────────────┐
-│ Key         │ Value                                │
-├─────────────┼──────────────────────────────────────┤
-│ id          │ 00000000-0000-0000-0001-000000000001 │
-│ email       │ user@example.com                     │
-│ tenant_id   │ 00000000-0000-0000-0002-000000000001 │
-│ expires_at  │ 2026-02-23T12:00:00+00:00            │
-└─────────────┴──────────────────────────────────────┘
-```
+### `logout`
 
-## Credential Caching
+```bash
+kscli logout
+```
 
-Credentials are stored at `/tmp/kscli/.credentials` by default (override with `KSCLI_CREDENTIALS_PATH`).
+Removes the credentials file. The config file (base URL, format preference) is left alone.
 
-**File format** (JSON):
+### `whoami`
 
-```json
-{
-  "token": "<jwt>",
-  "user_id": "00000000-...",
-  "tenant_id": "00000000-...",
-  "expires_at": "2026-02-23T12:00:00+00:00",
-  "admin_api_key": "your-admin-key"
-}
+```bash
+kscli whoami
+kscli whoami --format yaml
 ```
 
-The `admin_api_key` is persisted alongside the token so that automatic token refresh works without requiring the env var to be set on every invocation.
+Shows the identity the stored key resolves to — useful for confirming which user and tenant a machine is pointed at.
 
-## Auto-Refresh
+## Credential storage
 
-When any command calls `get_api_client()` (`src/kscli/client.py:38-50`), it triggers `load_credentials()` (`src/kscli/auth.py:60-80`) which:
+| Path | Purpose | Permissions |
+|---|---|---|
+| `/tmp/kscli/.credentials` | API key, JSON `{"api_key": "..."}` | `0600` |
+| `~/.config/kscli/config.json` | Base URL, TLS, default format | user default |
 
-1. Loads the credentials file
-2. Compares `expires_at` against the current UTC time
-3. If expired, calls `assume_user()` again using the cached `admin_api_key`, `tenant_id`, and `user_id`
-4. Returns the refreshed credentials transparently
+Override either location via environment variable:
+
+- `KSCLI_CREDENTIALS_PATH` — directory that holds `.credentials` (default `/tmp/kscli`). Point this at a persistent location (e.g. `~/.config/kscli`) if you don't want the key wiped on reboot.
+- `KSCLI_CONFIG` — full path to the config file.
+
+Example — persist the credentials file across reboots:
+
+```bash
+export KSCLI_CREDENTIALS_PATH=~/.config/kscli
+kscli login --api-key sk-user-...
+```
 
-This means long-running scripts or interactive sessions never break due to token expiry.
+## Pointing at a different environment
 
-## Error Handling
+`login --url` takes any base URL; it is persisted to the config file so subsequent commands don't need it again.
 
-Authentication-related errors produce specific exit codes (`src/kscli/client.py:24-30`):
+```bash
+# Local dev backend
+kscli login --api-key sk-user-... --url http://localhost:8000
 
-| HTTP Status | Message | Exit Code |
-|-------------|---------|-----------|
-| 401 | `Session expired. Run: kscli assume-user ...` | 2 |
-| 403 | `Permission denied` | 1 |
+# Production
+kscli login --api-key sk-user-... --url https://api.knowledgestack.ai
+```
 
-If you see exit code 2, re-run `assume-user` to re-authenticate:
+To hit a different base URL for a single command, pass `--base-url` on the root group:
 
 ```bash
-kscli assume-user --tenant-id <id> --user-id <id>
+kscli --base-url http://localhost:8000 folders list
 ```
 
 ## TLS / SSL
 
-For environments using self-signed certificates or corporate proxies:
+`login` auto-enables TLS verification when the URL is `https://`. For self-signed certs or corporate proxies:
 
 ```bash
-# Use a custom CA bundle
+# Custom CA bundle
 export KSCLI_CA_BUNDLE=/path/to/ca-bundle.crt
 
-# Disable SSL verification (development only)
+# Disable verification (dev only!)
 export KSCLI_VERIFY_SSL=false
 ```
 
-SSL configuration is resolved in `get_tls_config()` (`src/kscli/config.py:63-83`) and applied when building the API client (`src/kscli/client.py:43-48`).
+See [`src/kscli/config.py::get_tls_config`](../src/kscli/config.py) for the resolution logic.
 
-If SSL verification fails, the CLI prints troubleshooting steps (`src/kscli/client.py:88-98`):
+If verification fails, `kscli` prints troubleshooting steps:
 
 ```
 Error: SSL certificate verification failed.
@@ -145,3 +150,22 @@ Solutions:
 2. Set KSCLI_CA_BUNDLE to your custom CA bundle path
 3. (Insecure) Set KSCLI_VERIFY_SSL=false for development
 ```
+
+## Exit codes
+
+| Situation | Exit | Message |
+|---|---|---|
+| Success | `0` | — |
+| Auth failure (401) | `2` | `Session expired. Run: kscli login --api-key <key>` |
+| Not found (404) | `3` | `<resource> not found` |
+| Validation error (422) | `4` | Echoes the FastAPI validation body |
+| Any other failure | `1` | Generic error message |
+
+These come from `handle_client_errors()` in [`src/kscli/client.py`](../src/kscli/client.py).
+
+## Security notes
+
+- Treat a key like a password — it carries **all** permissions your user has.
+- Prefer one key per machine (or per CI runner). Revoke them individually when a device is decommissioned.
+- Never commit `/tmp/kscli/.credentials` or `~/.config/kscli/config.json`.
+- For CI, inject the key via secrets (`KSCLI_API_KEY` environment variable, then `kscli login --api-key "$KSCLI_API_KEY"`).
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 0000000..334712a
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,217 @@
+# Quickstart
+
+> 📚 **Reading this on GitHub?** The same page with embedded videos, zoomable screenshots, and a searchable TOC lives at **[docs.knowledgestack.ai/kscli/quickstart](https://docs.knowledgestack.ai/kscli/quickstart)**.
+
+Go from nothing installed to a working semantic search against your own documents in about two minutes. Every command below is real — copy, paste, substitute the placeholder IDs.
+
+<p align="center">
+  <a href="https://docs.knowledgestack.ai/kscli/demo">
+    <img src="https://docs.knowledgestack.ai/assets/kscli/quickstart-hero.gif"
+         alt="End-to-end quickstart in 45 seconds"
+         width="760" />
+  </a>
+</p>
+
+## Prerequisites
+
+- Python **3.12+** (`python --version`)
+- [**uv**](https://docs.astral.sh/uv/) installed (`uv --version`). On macOS: `brew install uv`.
+- A Knowledge Stack account at **[app.knowledgestack.ai](https://app.knowledgestack.ai)** — sign up with email/password or Google SSO.
+
+## 1. Install `kscli`
+
+```bash
+uv tool install kscli
+kscli --version
+```
+
+`uv tool install` builds an isolated venv and puts `kscli` on your `PATH`. Upgrade later with `uv tool upgrade kscli`.
+
+## 2. Create an API key
+
+<p align="center">
+  <img src="https://docs.knowledgestack.ai/assets/kscli/api-key-create.gif"
+       alt="Creating an API key from the My Account → API Keys dashboard"
+       width="720" />
+</p>
+
+`kscli` authenticates with a user-scoped API key. Keys begin with `sk-user-` and carry your user's permissions.
+
+1. Open **[app.knowledgestack.ai](https://app.knowledgestack.ai)** and sign in.
+2. Click your avatar (top-right) → **My Account**.
+3. Open the **API Keys** tab.
+4. Click **Create API key**.
+5. Label the key — pick something you'll still recognize six months from now (e.g. `kscli on macbook`, `kscli ingest job`).
+6. **Copy the key now.** It is shown exactly once. If you lose it, revoke and create a new one.
+
+> ⚠️ Treat the key like a password. Anyone with the key can act as you, including uploading and deleting documents.
+
+## 3. Log in
+
+<p align="center">
+  <img src="https://docs.knowledgestack.ai/assets/kscli/login.gif"
+       alt="kscli login validating the key and writing credentials"
+       width="720" />
+</p>
+
+```bash
+kscli login --api-key sk-user-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+What happens:
+
+1. `kscli` calls `GET /users/me` with the key as a bearer token.
+2. On success, the key is written to `/tmp/kscli/.credentials` with mode `0600`.
+3. The resolved base URL and TLS settings are saved to `~/.config/kscli/config.json`.
+4. You should see `Logged in successfully (https://api-staging.knowledgestack.ai).`
+
+Verify:
+
+```bash
+kscli whoami
+kscli whoami --format yaml   # includes tenant_id, email, roles
+```
+
+> **Different environment?** Pass `--url http://localhost:8000` (dev) or `--url https://api.knowledgestack.ai` (prod) to `login`. It is persisted to the config file.
+
+## 4. Find a folder to put documents in
+
+Every document lives under a folder. Every tenant has a root folder; you can create subfolders.
+
+```bash
+# See the whole folder tree
+kscli folders list --format tree
+```
+
+Pick a folder, grab its `path_part_id` (not `id` — see "PathPart vs domain ID" at the bottom of this page):
+
+```bash
+kscli folders describe <folder-id> --format yaml
+```
+
+Create a dedicated subfolder for this tutorial:
+
+```bash
+kscli folders create \
+    --name "kscli tutorial" \
+    --parent-path-part-id <parent-path-part-id>
+```
+
+The response includes `id` and `path_part_id`. Save the `path_part_id` of the new folder — the next step needs it.
+
+## 5. Ingest a document
+
+<p align="center">
+  <img src="https://docs.knowledgestack.ai/assets/kscli/ingest.gif"
+       alt="Ingesting a PDF and watching the workflow progress"
+       width="720" />
+</p>
+
+Grab any PDF from your Downloads folder and upload it.
+
+```bash
+kscli documents ingest \
+    --file ~/Downloads/some-report.pdf \
+    --path-part-id <tutorial-folder-path-part-id> \
+    --name "Some report"
+```
+
+Ingestion runs in the background on the server: the file is uploaded, queued onto an ingestion workflow, then chunked, embedded, and indexed. `kscli` returns immediately with the new document's `id` and a workflow handle.
+
+Watch the workflow progress:
+
+```bash
+kscli workflows list --limit 5
+kscli workflows describe <workflow-id>
+```
+
+When the workflow is `completed`, the document is fully indexed and searchable. Small PDFs take seconds; large ones take a minute or two.
+
+## 6. Run your first semantic search
+
+<p align="center">
+  <img src="https://docs.knowledgestack.ai/assets/kscli/search.gif"
+       alt="kscli chunks search rendering a Rich table of ranked results"
+       width="720" />
+</p>
+
+```bash
+kscli chunks search \
+    --query "what does the document say about revenue" \
+    --parent-path-ids <tutorial-folder-path-part-id> \
+    --limit 5
+```
+
+You'll get a Rich-table of top chunks sorted by relevance score. The `content` column holds the actual text that matched. Try:
+
+```bash
+# JSON for scripting
+kscli chunks search -q "revenue" --parent-path-ids <id> -f json | jq '.[0]'
+
+# Full-text instead of dense semantic
+kscli chunks search -q "exact phrase" --search-type full_text --parent-path-ids <id>
+
+# Filter by chunk type
+kscli chunks search -q "quarterly results" --chunk-types TABLE --parent-path-ids <id>
+```
+
+## 7. Browse what got ingested
+
+```bash
+# Documents in the folder
+kscli documents list --parent-path-part-id <tutorial-folder-path-part-id>
+
+# The latest version of a specific document
+kscli documents describe <document-id> --format yaml
+
+# All chunks in that version
+kscli chunks version-chunk-ids <version-id>
+```
+
+## 8. Clean up (optional)
+
+```bash
+kscli documents delete <document-id>
+kscli folders delete <folder-id>
+kscli logout
+```
+
+`kscli logout` removes the credentials file. The API key on the server is still valid — revoke it from the dashboard if you're done with it.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Not authenticated. Run: kscli login --api-key <key>` | No credentials file | Run `kscli login --api-key ...` |
+| Exit code `2`, `Session expired...` | Key revoked or invalid | Create a new key in the dashboard and re-login |
+| `SSL certificate verification failed` | Self-signed backend / corporate proxy | Set `KSCLI_CA_BUNDLE` or `KSCLI_VERIFY_SSL=false` for dev |
+| `kscli: command not found` after install | `uv tool` bin directory not on `PATH` | Run `uv tool update-shell` and open a new terminal |
+| Ingestion stuck in `running` | Worker not picking up tasks | Check backend workflow worker — `kscli workflows describe <id>` |
+| `422` on `folders create` | Passed a folder `id` where a `path_part_id` is required | Use `--format yaml` on `describe` to see both |
+
+## PathPart vs domain ID
+
+This is the one conceptual bump newcomers hit. Every folder has **two** UUIDs:
+
+- **`id`** — the folder's own record ID. Use with `describe`, `update`, `delete`.
+- **`path_part_id`** — its position in the folder tree. Use with anything that needs a *parent* — creating a child folder, ingesting a document under the folder, scoping a search.
+
+```bash
+kscli folders describe  <folder_id>                          # id
+kscli folders update    <folder_id> --name "Renamed"         # id
+kscli folders delete    <folder_id>                          # id
+
+kscli folders create    --parent-path-part-id <path_part_id> # path_part_id
+kscli documents ingest  --path-part-id       <path_part_id>  # path_part_id
+kscli chunks search     --parent-path-ids    <path_part_id>  # path_part_id
+```
+
+`kscli folders describe ... --format yaml` prints both so you can copy the right one.
+
+## Next steps
+
+- **Everything else is at [docs.knowledgestack.ai/kscli](https://docs.knowledgestack.ai/kscli)** — searchable reference, full video tutorials, release notes.
+- [Recipes](recipes.md) — bulk ingest a directory, pipe into jq, run searches from CI
+- [Authentication](authentication.md) — credential storage, TLS, exit codes
+- [Configuration](configuration.md) — env vars, config file, precedence
+- [Design patterns](design_patterns.md) — how the CLI is wired internally
diff --git a/docs/recipes.md b/docs/recipes.md
new file mode 100644
index 0000000..7e9646c
--- /dev/null
+++ b/docs/recipes.md
@@ -0,0 +1,211 @@
+# Recipes
+
+> 📚 **Hosted version:** [docs.knowledgestack.ai/kscli/recipes](https://docs.knowledgestack.ai/kscli/recipes) — includes screencasts for the bulk-ingest and CI recipes.
+
+<p align="center">
+  <img src="https://docs.knowledgestack.ai/assets/kscli/recipes-bulk-ingest.gif"
+       alt="Bulk ingesting a directory of PDFs with kscli folders bulk-ingest"
+       width="720" />
+</p>
+
+Common `kscli` workflows. Every snippet assumes you've already run `kscli login`.
+
+## Bulk ingest a directory of PDFs
+
+The `folders bulk-ingest` verb uploads every file in a local directory to a target folder in one shot.
+
+```bash
+# Dry-run first — prints what would be uploaded without touching the server
+kscli folders bulk-ingest ~/Documents/annual-reports \
+    --folder-id <tutorial-folder-id> \
+    --extensions .pdf \
+    --dry-run
+
+# Execute
+kscli folders bulk-ingest ~/Documents/annual-reports \
+    --folder-id <tutorial-folder-id> \
+    --extensions .pdf,.docx,.md
+```
+
+Pair with `kscli workflows list --limit 50` to watch the ingestion workflows drain.
+
+## Search from a shell script
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+QUERY="${1:?usage: search.sh <query>}"
+FOLDER="${KSCLI_SEARCH_FOLDER:-<your-folder-path-part-id>}"
+
+kscli chunks search \
+    --query "$QUERY" \
+    --parent-path-ids "$FOLDER" \
+    --limit 10 \
+    --format json \
+  | jq -r '.[] | "[\(.score | tostring | .[0:4])] \(.content)"'
+```
+
+Usage:
+
+```bash
+./search.sh "quarterly revenue drivers"
+```
+
+## Pipe IDs into another command
+
+`--format id-only` emits one ID per line — perfect for `xargs`.
+
+```bash
+# Delete every empty folder under a parent
+kscli folders list --parent-path-part-id <parent> -f id-only \
+  | xargs -I {} kscli folders delete {}
+
+# Re-run every failed workflow from the last hour
+kscli workflows list --status failed -f id-only \
+  | xargs -I {} kscli workflows rerun {}
+```
+
+## Extract the top search hit as structured data
+
+```bash
+kscli chunks search -q "latency SLO" --parent-path-ids <id> -f json \
+  | jq '{id: .[0].id, score: .[0].score, content: .[0].content}'
+```
+
+## Ingest a document and wait for it to be searchable
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+FILE="$1"
+FOLDER="$2"
+
+result=$(kscli documents ingest --file "$FILE" --path-part-id "$FOLDER" -f json)
+workflow_id=$(echo "$result" | jq -r '.workflow_id')
+
+echo "Ingested. Waiting for workflow $workflow_id..."
+until [ "$(kscli workflows describe "$workflow_id" -f json | jq -r .status)" = "completed" ]; do
+  sleep 2
+done
+echo "Ready to search."
+```
+
+## Run a search from GitHub Actions
+
+```yaml
+# .github/workflows/search-knowledge.yml
+name: Query knowledge base
+
+on:
+  workflow_dispatch:
+    inputs:
+      query:
+        description: "Search query"
+        required: true
+
+jobs:
+  search:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: astral-sh/setup-uv@v3
+      - name: Install kscli
+        run: uv tool install kscli
+      - name: Log in
+        env:
+          KSCLI_API_KEY: ${{ secrets.KSCLI_API_KEY }}
+        run: kscli login --api-key "$KSCLI_API_KEY" --url https://api.knowledgestack.ai
+      - name: Search
+        run: |
+          kscli chunks search \
+            --query "${{ inputs.query }}" \
+            --parent-path-ids ${{ vars.KSCLI_FOLDER_ID }} \
+            --format json \
+            --limit 5 > results.json
+      - uses: actions/upload-artifact@v4
+        with:
+          name: search-results
+          path: results.json
+```
+
+Store the key in repository secrets as `KSCLI_API_KEY` and the folder ID in repository variables as `KSCLI_FOLDER_ID`.
+
+## Tag documents for filtered search
+
+```bash
+# Create a tag
+tag_id=$(kscli tags create --name "q4-reports" -f id-only)
+
+# Attach it to a folder (propagates to every document inside)
+kscli tags attach --tag-id "$tag_id" --path-part-id <folder-path-part-id>
+
+# Filter search by tag
+kscli chunks search \
+    --query "revenue growth" \
+    --tag-ids "$tag_id" \
+    --limit 5
+```
+
+## Copy a document between folders (by re-ingesting)
+
+There is no `move` verb — download the source file locally, then ingest under the new folder.
+
+```bash
+# 1. Get the current version's contents
+kscli document-versions contents <version-id> > /tmp/copy.bin
+
+# 2. Re-ingest under the target folder
+kscli documents ingest \
+    --file /tmp/copy.bin \
+    --path-part-id <new-folder-path-part-id> \
+    --name "Copied report"
+```
+
+## Switch between local dev and prod quickly
+
+Keep credentials for each environment in separate directories:
+
+```bash
+# Local dev
+export KSCLI_CREDENTIALS_PATH=~/.config/kscli-local
+export KSCLI_CONFIG=~/.config/kscli-local/config.json
+kscli login --api-key sk-user-local... --url http://localhost:8000
+
+# Production
+export KSCLI_CREDENTIALS_PATH=~/.config/kscli-prod
+export KSCLI_CONFIG=~/.config/kscli-prod/config.json
+kscli login --api-key sk-user-prod... --url https://api.knowledgestack.ai
+```
+
+Wrap the two in shell functions (`kscli-local`, `kscli-prod`) to flip between them.
+
+## YAML for config review, table for humans, JSON for scripts
+
+```bash
+kscli settings show --format yaml        # quick eyeball check
+kscli folders list --format table        # daily use
+kscli folders list --format json | jq    # scripting
+kscli folders list --format tree         # hierarchy at a glance
+```
+
+## Troubleshoot a stuck ingestion
+
+```bash
+# Find recent workflows
+kscli workflows list --limit 10
+
+# Drill into one
+kscli workflows describe <workflow-id> --format yaml
+
+# Cancel and re-run
+kscli workflows cancel <workflow-id>
+kscli workflows rerun  <workflow-id>
+```
+
+## See also
+
+- **[docs.knowledgestack.ai/kscli](https://docs.knowledgestack.ai/kscli)** — full docs home with video tutorials
+- [Quickstart](quickstart.md) — the happy path for new users
+- [Authentication](authentication.md) — API key flow, credential storage
+- [Configuration](configuration.md) — env vars, precedence, TLS