@4ort/cli 0.8.5 → 0.8.6

package/dist/index.js

@@ -34,7 +34,7 @@ const program = new Command();
 program
     .name("4ort")
     .description("Unified CLI for the 4ort ecosystem — hosting, knowledge graph, and more")
-    .version("0.8.5");
+    .version("0.8.6");
 // ─────────────────────────────────────────────────────────────────────
 // 4ort.net subdomain hosting
 // ─────────────────────────────────────────────────────────────────────

package/docs/MCP.md

@@ -0,0 +1,77 @@
+# 🧠 `4ort mcp` — Run the CLI as an MCP server
+
+`@4ort/cli` is **both a CLI and an MCP server** in the same binary. Every
+subcommand surface (`kg`, `mov`, `web`, `vault run`, etc.) becomes an MCP tool
+when the CLI is launched in MCP mode — so any MCP-speaking agent gets the
+entire galaxy toolkit for free, without re-implementing anything.
+
+## Two modes
+
+```bash
+4ort mcp stdio     # local: pipe to a Claude/agent runner via stdin/stdout
+4ort mcp serve     # network: expose the MCP server over HTTP (for remote agents)
+```
+
+## stdio mode (most common)
+
+Wire the CLI as an MCP server in a Claude Desktop / Claude Code / Cursor / any
+MCP client config. Example (Claude Code-style):
+
+```jsonc
+{
+  "mcpServers": {
+    "4ort": {
+      "command": "4ort",
+      "args": ["mcp", "stdio"]
+    }
+  }
+}
+```
+
+The agent will discover tools like:
+- `4ort.kg.search`, `4ort.kg.ask`, `4ort.kg.entity`, `4ort.kg.match`,
+  `4ort.kg.popularity`, `4ort.kg.trending`, `4ort.kg.agent-context`,
+  `4ort.kg.article-context`
+- `4ort.mov.publish`, `4ort.mov.render`, `4ort.mov.list`
+- `4ort.web.get`
+- `4ort.search` (smart router)
+- `4ort.run` (vault-resolved subprocess)
+
+Identity is the CLI's existing `~/.4ort/config.json` — whichever keys you've
+configured (4ort.net, kg, vault) flow through to the agent.
+
+## serve mode (network)
+
+For remote agents or shared infrastructure:
+
+```bash
+4ort mcp serve --port 8080
+```
+
+Exposes the same tool surface over HTTP transport. Pair with reverse-proxy +
+auth as needed (the CLI itself doesn't add network auth — bring your own).
+
+## Where this fits in the galaxy
+
+- **Mission Control panels (ADR-0002 MCP-as-panels)** — the 4ort.ai agent can
+  call `4ort.kg.*` and `4ort.mov.*` tools directly via this surface; sidebar
+  panels render the results.
+- **The code-command sandbox** ships `@4ort/cli` baked into the image so every
+  spawned agent has these tools natively, no MCP wiring needed inside the
+  sandbox itself.
+- **The future "MCP Uplink"** property (galaxy plan
+  `plans/MCP_UPLINK_PLAN.md`) mounts `@4ort/cli` alongside open MCP servers
+  (Gmail, Slack, GitHub, etc.) into a unified MCP gateway.
+
+## Composing with the vault
+
+`4ort run` is also exposed as an MCP tool — meaning an agent can ask the CLI to
+**run a subprocess with vault-resolved secrets** without ever seeing the raw
+values. Great for "run my SQL migration with the prod DB password" workflows
+where the agent should never touch the secret.
+
+## Versioning / surface stability
+
+The MCP tool names and schemas track the CLI's commander.js definitions
+directly. When a new subcommand lands in the CLI, it's available as an MCP
+tool in the next published version (`npm install -g @4ort/cli@latest`).

package/docs/MOV.md

@@ -0,0 +1,136 @@
+# 🎬 `4ort mov` — Publishing video to 4ort.mov
+
+Since `@4ort/cli@0.6.0` (`publish`) + `0.7.0` (`render`). Two complementary
+flows for getting video onto the galaxy's PeerTube host (4ort.mov).
+
+## Setup
+
+```bash
+# one-time: mint your OWN 4ort.mov account + render token, then sign in with it
+4ort provision run video
+4ort mov login --provisioned
+
+# or sign in to an existing account interactively / non-interactively
+4ort mov login                       # prompts for username + password
+4ort mov login -u <user> -p <pass>   # non-interactive (agents/CI; or env
+                                     # FORT_MOV_USERNAME / FORT_MOV_PASSWORD)
+```
+
+All credentials persist to `~/.4ort/config.json` (mode `0600`). The CLI
+authenticates via PeerTube's OAuth on `/api/*`, so it never needs a separate
+site/gate credential.
+
+## Accounts & channels (per-user)
+
+`4ort mov` is **per-account**. Every user/agent has their own 4ort.mov account,
+so videos publish under **their own channel** — not a shared one.
+
+```bash
+# one-time: mint your own account + render token
+4ort provision run video
+4ort mov login --provisioned     # or: 4ort mov login -u <user> -p <pass>
+```
+
+**Which channel does a publish go to?**
+
+- No `--channel` → your account's **default (first) channel**.
+- `--channel <name>` → a channel **you own** by that name/displayName (the
+  command errors and lists your channels if there's no match).
+- `4ort mov channels --create <name>` → make a new channel under your account.
+
+So two agents running `4ort mov publish` land in two different channels — each
+writes only to its own account. (Admin/`root` is just another account; the
+autonomous pipelines historically published as `root`, but provisioned agents
+get their own.)
+
+## Two flows
+
+### Flow A — Direct publish (you have an MP4)
+
+```bash
+4ort mov publish ./my-video.mp4 \
+  --title "My Video" \
+  --channel galaxy \
+  --description "..." \
+  --thumbnail ./thumb.png \
+  --privacy unlisted
+```
+
+- Single-request multipart upload (`POST /api/v1/videos/upload`)
+- Prints the watch URL on success
+- Privacy: `public` / `unlisted` / `private` / `internal` (default `unlisted`)
+
+### Flow B — Render-and-publish (you have a HyperFrames composition dir)
+
+```bash
+4ort mov render ./my-composition --publish \
+  --title "My Composition" \
+  --channel galaxy
+```
+
+End-to-end agent publish chain in one command:
+
+```
+local dir of HyperFrames composition
+     │
+     ▼ tar (gitignore-respecting)
+     ▼
+POST to factory.4ort.mov (video-factory)
+     │
+     ▼ async job (poll for status)
+     ▼
+MP4 + preview frames back
+     │
+     ▼ (if --publish)
+     ▼
+4ort mov publish (under-the-hood)
+     │
+     ▼
+watch URL printed
+```
+
+This is the **path that 4ort.ai's agents inside the code-command sandbox use**
+to publish content end-to-end — the bridge spec is in `~/ai/code-command/docs/`
+and the engine is at `~/ai/4ort.mov/engine/`.
+
+## Other commands
+
+| Command | What it does |
+|---|---|
+| `4ort mov list` | List your videos on 4ort.mov |
+| `4ort mov channels` | List channels; `--create <name>` to make one |
+| `4ort mov delete <id>` | Delete a video (with confirm) |
+
+## Where this fits in the galaxy
+
+| Property | Role |
+|---|---|
+| **4ort.mov** | The PeerTube host (`~/ai/4ort.mov/`) — final destination for all videos |
+| **video-factory** | Render engine at `factory.4ort.mov` (lives in `~/ai/4ort.mov/engine/`) — turns HyperFrames compositions into MP4s |
+| **4ort-tv** | Long-form video pipeline — outputs HyperFrames compositions that get rendered + published via this CLI |
+| **4ort.stream** | Short-form autonomous pipeline — outputs MP4s directly; uses `4ort mov publish` (Flow A) |
+| **code-command sandbox** | Ships `@4ort/cli` baked in; the `4ort mov render --publish` chain is how spawned agents publish |
+
+## Auth model
+
+The CLI talks to PeerTube exclusively over `/api/*` using an OAuth bearer
+token (password grant at `4ort mov login`, transparently refreshed on 401).
+Any human-facing password wall on `4ort.mov` carves out `/api/*` (see
+`~/ai/4ort.mov/docs/AS-BUILT.md`, ADR-0009), so **automated publishes need no
+separate gate credential** — the bearer token is the only auth the CLI sends.
+Per-property security posture is in
+`~/ai/4ort-galaxy/property-notes/4ort-mov.md`.
+
+## Versioning / what's new
+
+- **0.6.0** — `4ort mov publish`: PeerTube upload + login + list/channels/delete
+- **0.7.0** — `4ort mov render`: dir → video-factory → optional publish in one command
+- **0.8.0** — `4ort provision run video` mints a per-agent 4ort.mov account + render
+  token; `4ort mov login --provisioned` signs in with it
+- **0.8.4** — shipped a verified, lint-passing render starter template at
+  `examples/fact-short.html` (`4ort mov render examples/fact-short.html -q draft`)
+- **0.8.5** — publish reliability: PeerTube token refresh now recovers from an
+  expired/rotated refresh token via a password-grant fallback (env or stored
+  credentials), so long-lived render hosts keep publishing
+- **0.8.6** — docs: documented the per-account channel model + provisioned login,
+  corrected the upload method (multipart, not resumable), refreshed the auth model

package/docs/VAULT.md

@@ -0,0 +1,86 @@
+# 🔑 `4ort vault` + `4ort run` — Secrets layer
+
+Since `@4ort/cli@0.5.0`. The galaxy's secrets layer, modeled directly on
+**1Password's `op run`** pattern: secrets live server-side in the 4ort.ai
+vault, the CLI fetches them at invocation time, and they're **injected
+into the child process only** — never written to disk.
+
+## The model in one line
+
+```
+secret ref in env  →  4ort run resolves it  →  child process gets the real value  →  exit
+                                                ↑
+                                       (plaintext never touches disk)
+```
+
+## Setup (one time per machine)
+
+```bash
+# 1. Get a vault token from Mission Control (4ort.ai → Secrets panel)
+#    The token is prefixed `4vt_…`
+
+# 2. Link this machine
+4ort vault login
+# → paste the 4vt_ token when prompted
+
+# 3. Verify
+4ort vault status
+# → prints: server, vault user, token (masked), connection OK
+```
+
+Token gets persisted to `~/.4ort/config.json` under `vault.token` (file mode `0600`).
+Vault server defaults to `https://4ort.ai`.
+
+## Using it
+
+### Reference secrets in env at runtime
+
+The reference shape is `4ort://service[/name]`:
+
+```bash
+# .env or shell:
+OPENAI_API_KEY=4ort://openai
+DATABASE_URL=4ort://postgres/prod
+SLACK_TOKEN=4ort://slack/team-a
+```
+
+### Run a command with refs resolved
+
+```bash
+4ort run -- python my_script.py
+4ort run -- npm start
+4ort run -- /usr/bin/env  # see what got injected (for debugging)
+```
+
+At invocation:
+1. CLI scans the env of the parent shell + any `.env` file in cwd
+2. For each `4ort://…` ref, fetches the real value from the vault
+3. Spawns the child process with the real values in its env
+4. Plaintext exists only in the child's memory; never lands on disk
+
+## Other commands
+
+| Command | What it does |
+|---|---|
+| `4ort vault login` | Paste a `4vt_` token; persist to `~/.4ort/config.json` |
+| `4ort vault status` | Show current vault identity + connection check |
+| `4ort vault logout` | Wipe the vault token (other identities preserved) |
+
+## Where this fits in the galaxy
+
+- **Same vault backend as the 4ort.ai Secrets panel** — the CLI is a peer client;
+  every UI write is visible to `4ort run` instantly.
+- **The code-command sandbox** uses the CLI inside spawned interpreters via
+  `FORT_CLI_CONFIG_B64` env (the config is materialized into the sandbox at
+  spawn-time so the sandboxed agent has vault access without seeing the token).
+- **The future "MCP Uplink"** property layers on top: third-party OAuth tokens
+  (Gmail / Slack / GitHub) get stored in the same vault, keyed by galaxy JWT
+  user-id. See `plans/MCP_UPLINK_PLAN.md` in the galaxy repo.
+
+## Security posture
+
+- Vault token is the only persistent secret on the machine
+- Per-service secrets are fetched fresh per `4ort run` invocation
+- `0600` perms on `~/.4ort/config.json`
+- Never echo `4ort vault status` output into logs (token is masked but the
+  shape gives away the service has one)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4ort/cli",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "Unified CLI for the 4ort ecosystem — 4ort.net hosting, knowledge graph, and more",
   "type": "module",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "dist",
     "README.md",
-    "examples"
+    "examples",
+    "docs"
   ],
   "scripts": {
     "dev": "tsx src/index.ts",