@khotan/cli 0.6.0 → 0.9.0

package/README.md

@@ -101,6 +101,7 @@ state is needed in CI or sandboxes:
 | `KHOTAN_API_URL`  | API origin (e.g. `https://app.example.com`) |
 | `KHOTAN_API_KEY`  | Organization-scoped API key               |
 | `KHOTAN_PROFILE`  | Select a stored profile by name           |
+| `KHOTAN_ORG_ID`   | Expected org id; the CLI asserts `whoami.organizationId` matches it and fails closed otherwise |
 
 ```bash
 export KHOTAN_API_URL=https://app.example.com
@@ -108,6 +109,27 @@ export KHOTAN_API_KEY=khk_live_...
 khotan apps list --json | jq '.apps[].id'
 ```
 
+### Repo-local org isolation (`env.khotan.local`)
+
+When an `env.khotan.local` file sits at (or above) the working directory, the CLI
+auto-loads its `KHOTAN_*` values so every command is scoped to that repo's
+organization — never a stray machine-global profile from another customer. The
+file is authoritative: its values win over shell-exported `KHOTAN_*`, which win
+over the stored profile, and CLI flags win over everything (`flag >
+env.khotan.local > shell env > profile`).
+
+```bash
+# env.khotan.local (git-ignored; never commit secrets)
+KHOTAN_API_URL='https://<customer>.khotan.com'
+KHOTAN_API_KEY='<org-scoped key>'
+KHOTAN_ORG_ID='<org id>'
+```
+
+When `KHOTAN_ORG_ID` (or `--assert-org <id>`) is set, every operation and
+`khotan mcp serve` verifies `whoami.organizationId` matches before trusting
+output and fails closed on mismatch (`error [org_mismatch]`). With no expected
+org id set, behavior is unchanged.
+
 ## Command surface
 
 Commands are grouped by domain and derived from the capability catalog, so the
@@ -120,7 +142,7 @@ documented surface and the executable surface cannot drift. Run `khotan help` or
 | App env   | `apps env list <id>`, `apps env set <id> <KEY> --value V`, `apps env reveal <id> <KEY>`, `apps env unset <id> <KEY>`, `apps env bulk-set <id> --var A=1 --var B=2` |
 | Pipelines | same shape as apps under `pipelines …` |
 | Databases | `databases list`, `databases create --name db`, `databases connection <id>`, `databases rotate-credentials <id>`, `databases delete <id>` |
-| Files     | `files list`, `files get <id>`, `files upload <path>`, `files download <id> --output <path>`, `files update <id> --name new.txt`, `files delete <id>` |
+| Files     | `files list`, `files get <id>`, `files upload <path>`, `files download <id> --output <path>`, `files download-url <id>`, `files preview-url <id>`, `files update <id> --name new.txt`, `files delete <id>` |
 | Folders   | `folders list`, `folders create --name docs`, `folders rename <id> --name new`, `folders delete <id>` |
 | Context   | `context list`, `context get <slug>`, `context raw <slug>`, `context create --title T --kind knowledge --content '...'`, `context update <slug> --expected-revision 3 --content '...'`, `context delete <slug>` |
 
@@ -151,6 +173,17 @@ khotan files upload ./report.pdf --folder-path /reports/2026
 khotan files download file_123 --output ./report.pdf
 ```
 
+To hand a file to a browser instead of saving it locally, mint a short-lived
+presigned URL and load it directly (no API key on the URL; expires in ~5 minutes):
+
+```bash
+khotan files preview-url file_123     # inline disposition, images and PDFs only
+khotan files download-url file_123    # attachment disposition, any file type
+```
+
+See [Serving file attachments](../../docs/files-api-attachments.md) for the full
+preview/download flow and the receiver wiring guidance.
+
 ## MCP server
 
 `khotan mcp serve` starts a local stdio MCP server that reuses the same profile,