@agora-build/atem 0.6.10 → 0.6.13

package/README.md

@@ -16,6 +16,12 @@ curl -fsSL https://dl.agora.build/atem/install.sh | bash
 
 Both download a prebuilt binary for your platform (linux-x64, linux-arm64, darwin-x64, darwin-arm64).
 
+The npm package downloads the binary for its published version. Documentation
+on GitHub `main` can describe features newer than the latest release. Check
+`atem --version` and `atem cred --help`; use a current release that includes
+the commands you need, or build from source below. Run a source build using
+its explicit path, such as `./target/release/atem`, to avoid an older installed CLI.
+
 ## Commands
 
 ```bash
@@ -28,8 +34,63 @@ atem repl                               # Interactive REPL with AI command inter
 ```bash
 atem login                              # Log in with Agora Console (opens browser)
 atem logout                             # Log out from SSO
+atem pair                               # Pair with Astation, then verify this device
+atem pair --save                        # Same, and keep credentials for offline use
+atem unpair [--yes]                     # Remove all Astation pairings (asks first)
+```
+
+`atem login` unlocks a limited set: project list, tokens for the active
+project, and the dev servers (`serv rtc`, `serv convo`, `serv webhooks`).
+Pairing with Astation unlocks the full set: vault, sync, memory, skills,
+`atem cred`, and Astation-driven remote agent control, voice coding, mark
+tasks and diagrams. `serv files`, `config`, and tokens from
+`AGORA_APP_ID`/`AGORA_APP_CERTIFICATE` need neither.
+
+`atem pair` receives your Agora login from Astation, then verifies the device:
+atem and your Mac each show a 12-character safety code. If they match, type
+`y` here; on the Mac click **Codes Match**, then approve with Touch ID.
+Either side can finish first. atem reads that `y` from the terminal itself,
+never from piped input or keys typed earlier, so run `atem pair` in an
+interactive terminal. If verification fails, the pairing stays saved, Astation
+is told, and `atem pair` exits nonzero; run it again to verify. A connected or SSO-paired session alone does not
+mean the device is verified; check `atem cred status`. With `--save`
+the credentials keep working when Astation disconnects; without it they stop
+5 minutes after the disconnect (atem asks when `--save` isn't given).
+
+### Device keys (`atem cred`)
+
+```bash
+atem cred status                        # Show whether this device is verified, its home Astation and its key agent
+atem cred unlock                        # Unlock this device's keys (approve with Touch ID on your Mac)
+atem cred lock                          # Wipe unlocked keys and stop the key agent
+atem cred projects                      # Send known Git projects to Astation's credential picker (keys must be unlocked)
 ```
 
+This device's keys are sealed on disk under a storage key that only the paired
+Mac (the home Astation) holds. `atem cred unlock` asks the Mac for it (Touch
+ID) and starts a background `atem key-agent` that holds the keys in memory.
+`atem cred lock` wipes them and stops the agent. After upgrading atem, run
+`atem cred lock` then `atem cred unlock` to pick up the new agent.
+
+`atem cred projects` sends this repo's Git remote, and the project names atem
+remembers, to Astation's credential picker, encrypted to your Mac. An
+unlocked atem also sends it on its own whenever it connects to Astation (the
+TUI, `atem pair`, and right after `atem cred unlock`), so you need
+`atem cred projects` only to send it right away from another repo. Retrieving
+values from Astation's local Credentials store (`atem cred get/list`) is not
+available yet; it is described in the
+[encryption design](https://github.com/Agora-Build/Atem/blob/main/designs/e2e-encryption.md).
+
+Updated clients and key agents retain the remote's original capitalization,
+such as `github.com/Agora-Build/Atem`; project identity and duplicate checks
+ignore case. Older clients/agents may report lowercase names. Reports are
+encrypted even when memory encryption is off and can remain in the picker
+after the sending command exits. You can also enter another Git remote in
+Astation's Credentials editor.
+
+See [pairing, unlocking and project suggestions](https://github.com/Agora-Build/Atem/blob/main/docs/credentials.md)
+for the steps when Atem runs on another machine and for upgrade troubleshooting.
+
 ### Tokens
 
 ```bash
@@ -65,6 +126,22 @@ atem config convo --validate            # Validate existing config without modif
 atem config convo --config <PATH>       # Use a specific config file
 ```
 
+### Vault (shared cross-agent context)
+
+```bash
+atem vault new --summary "auth refactor context"   # Create a vault, prints its id
+atem vault list                                     # List vaults you can read
+atem vault read --vault-id <id>                     # Current contents
+atem vault read --vault-id <id> --history           # Every version (shown eN vM)
+atem vault read --vault-id <id> --format plain      # Bare text (pipe into a prompt)
+atem vault write --vault-id <id> --text "decided: JWT in cookie"   # Append an entry
+atem vault write --vault-id <id> --entry-id 3 --text "..."         # Override entry e3
+atem vault set-summary --vault-id <id> --text "..."  # Update the summary
+```
+
+Requires pairing with Astation. Lets multiple atems (each driving an agent)
+share a versioned, append-only context store hosted on the Astation relay.
+
 ### Memory & Skills (shared across agents and machines)
 
 Requires pairing with Astation. Agents learn from each other: facts and skills
@@ -83,12 +160,16 @@ atem memory search "valkey"                      # Local full-text search (offli
 atem memory replace <id> "the fact as it is now" # New fact replaces the old one (history kept)
 atem memory invalidate <id>                      # Mark outdated without a replacement
 atem memory rm <id>                              # Remove everywhere
+atem memory purge <id> [--yes]                   # Remove a fact that contained a credential, stop re-harvesting it (asks first)
+atem memory apply                                # Rewrite the managed blocks and skills from the local store
 atem memory status                               # Account, machine, project, pending changes
 
 atem skill add ./my-skill                        # Directory with SKILL.md (global by default)
 atem skill list
+atem skill rm <name>                             # Remove everywhere
 atem skill history <name>                        # Every version, newest first
 atem skill restore <name> --version 3            # Re-push an old version as a new one
+atem skill purge <name> --version 3 [--yes]      # Erase versions that contained a credential (or --all-versions; asks first)
 ```
 
 Listings show short ids like `8245ecf6…e6fe` (first 8 + last 4 characters).
@@ -103,7 +184,33 @@ Memories are applied as a managed block in `~/.claude/CLAUDE.md`,
 `~/.codex/AGENTS.md` and `<repo>/CLAUDE.local.md`; skills go to
 `.claude/skills` and `.agents/skills`. Files tracked by git are never written.
 Anything that looks like a credential value is refused; save the
-credential's name, never its value. See `designs/atem-memory.md`.
+credential's name, never its value. See the [memory design](https://github.com/Agora-Build/Atem/blob/main/designs/atem-memory.md).
+
+Works with end-to-end encryption on or off. When it is on, changes sync only
+while the device is unlocked (`atem cred unlock`); see below.
+
+### End-to-end encryption
+
+Turned on or off in Astation (Settings > Security > End-to-End Encryption).
+When it is on, memory content, skill files and vault content are encrypted on
+this machine before they reach the relay, and project names become keyed hashes.
+Your Mac, verified Atem devices holding the account key, and holders of the
+recovery material can decrypt that content. The relay still sees routing identifiers and metadata,
+such as timestamps and ciphertext sizes; it is not authoritative for device
+trust or encryption state. Migration cannot prove that a server erased old
+plaintext backups.
+
+The device must be verified (`atem pair`) and unlocked (`atem cred unlock`).
+While it is locked, `atem sync` keeps changes queued. Switching encryption on
+or off migrates existing data; each verified atem finishes its part at its next
+`atem cred unlock` (`atem sync` alone doesn't contact Astation). **Turning on**
+or **Turning off** is a pending migration, even when the field counts show
+no remaining plaintext or obsolete fields. Astation commits the final state
+after accepting a verified migration completion; the CLI can then disconnect.
+Turning encryption off migrates shared data to plaintext; local Astation
+Keychain credentials keep their protection. The local `knowledge.db` stays
+plain text (mode 0600). See the [user guide](https://github.com/Agora-Build/Atem/blob/main/docs/credentials.md)
+and [protocol design](https://github.com/Agora-Build/Atem/blob/main/designs/e2e-encryption.md).
 
 ### Dev Servers
 
@@ -119,6 +226,8 @@ atem serv rtc --background              # Run as background daemon
 atem serv diagrams                      # Host diagrams from SQLite (HTTP)
 atem serv diagrams --port 9000
 atem serv diagrams --background
+atem serv files ~/docs                  # Serve a directory or file over HTTPS (Markdown rendered)
+atem serv files ~/docs --background     # Port auto-picked; reused next run
 atem serv webhooks                      # Receive Agora webhooks locally (auto-tunneled via ngrok)
 atem serv webhooks --no-tunnel          # Local listener only — bring your own tunnel
 atem serv webhooks --background         # Run as background daemon
@@ -142,6 +251,8 @@ done
 
 **`serv diagrams`** — SQLite-backed HTTP server for hosting AI-generated HTML diagrams.
 
+**`serv files`** — serves a directory (or a single file) over HTTPS. Markdown is rendered to HTML; append `?raw=1` to any URL for the raw bytes. Useful for browsing AI-generated docs on a remote machine.
+
 **`serv webhooks`** — local receiver for Agora webhook events (ConvoAI: `agent_joined`, `agent_left`, `agent_history`, `agent_error`, `agent_metrics`, …; RTC NCS events). Validates `Agora-Signature-V2` (HMAC-SHA256) when a `secret` is configured in `webhooks.toml`; accepts unsigned events otherwise with a warning. Live web console at `http://127.0.0.1:9090/` shows incoming events; each event also prints a one-line summary to stdout. Default tunnel provider is **ngrok**; set `tunnel_provider = "cloudflared"` for zero-auth quick tunnels. Use `--no-tunnel` if you're running cloudflared / ngrok separately for stable URLs across atem restarts.
 
 **Channel placeholders** — `--channel` accepts `{appid}` (first 12 chars of the active app id) and `{ts}` (unix epoch seconds at startup). Useful in for-loops to match the auto-gen channel format.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agora-build/atem",
-  "version": "0.6.10",
+  "version": "0.6.13",
   "description": "A terminal that connects people, Agora platform, and AI agents.",
   "bin": {
     "atem": "bin/atem"