@lifeaitools/clauth 1.19.4 → 1.30.2

package/README.md

@@ -27,37 +27,37 @@ At the end it prints a **bootstrap token** — save it for the next step.
 
 ---
 
-## After Install — Register Your Machine
-
-```bash
-clauth setup
-```
+## After Install — Register Your Machine
+
+```bash
+clauth setup
+```
 
 Prompts for: machine label, password, bootstrap token (from `clauth install`).
 
-Then verify:
-```bash
-clauth test      # → PASS
-clauth status    # → 12 services, all NO KEY
-```
-
-### Add A New Computer
-
-On an old computer where clauth is already registered:
-
-```bash
-clauth enroll --label "Dave-New-Laptop"
-```
-
-This creates a one-time enrollment code tied to the same `install_id` and writes
-a one-time PowerShell setup script. Move that script to the new computer and run
-it. The script installs clauth, enrolls the computer, installs startup, then
-deletes itself. Setup defaults the machine label to the computer name and only
-asks you to set the new computer's local clauth password.
-
-The enrollment code does not copy repo credentials into the script. It lets the
-new hardware-bound `machine_hash` join the shared Supabase Vault once. After the
-code is redeemed, it cannot be used again.
+Then verify:
+```bash
+clauth test      # → PASS
+clauth status    # → 12 services, all NO KEY
+```
+
+### Add A New Computer
+
+On an old computer where clauth is already registered:
+
+```bash
+clauth enroll --label "Dave-New-Laptop"
+```
+
+This creates a one-time enrollment code tied to the same `install_id` and writes
+a one-time PowerShell setup script. Move that script to the new computer and run
+it. The script installs clauth, enrolls the computer, installs startup, then
+deletes itself. Setup defaults the machine label to the computer name and only
+asks you to set the new computer's local clauth password.
+
+The enrollment code does not copy repo credentials into the script. It lets the
+new hardware-bound `machine_hash` join the shared Supabase Vault once. After the
+code is redeemed, it cannot be used again.
 
 ---
 
@@ -88,13 +88,13 @@ clauth get github
 ## Command Reference
 
 ```
-clauth install              Provision Supabase + install Claude skill
-clauth setup                Register this machine with the vault
-clauth enroll               Create one-time code to add another computer
-clauth status               All services + state
-clauth search <query>       Find services by name, project, description, or type
-clauth search <query> --addresses
-                            Also search redacted address hints (may read multiple secrets)
+clauth install              Provision Supabase + install Claude skill
+clauth setup                Register this machine with the vault
+clauth enroll               Create one-time code to add another computer
+clauth status               All services + state
+clauth search <query>       Find services by name, project, description, or type
+clauth search <query> --addresses
+                            Also search redacted address hints (may read multiple secrets)
 clauth test                 Verify connection
 
 clauth write key <service>  Store a credential
@@ -137,81 +137,98 @@ Nothing stored locally. Password never persisted. Machine hash is one-way only.
 
 clauth runs as an HTTP daemon on `http://127.0.0.1:52437`. The daemon provides:
 
-- **Web UI** — unlock vault, manage services, configure mounts
-- **REST API** — `GET /knowledge`, `GET /status`, `GET /v/<service>`, `GET /ping`, `POST /restart`, `GET /shutdown`
-- **MCP server** — Model Context Protocol for Claude Code and claude.ai
-- **Cloudflare Tunnel** — exposes MCP endpoints publicly for claude.ai connectors
-
-Start: `clauth serve start` (starts locked, auto-opens browser for unlock).
-
-Full daemon operations reference: see `regen-root/.claude/rules/clauth.md`.
-
-### Safe Metadata Cache
-
-Agents and scripts must discover services through metadata endpoints, not by
-walking every secret endpoint. The daemon caches service metadata for 30 seconds:
-
-```bash
-curl -s http://127.0.0.1:52437/knowledge      # sanitized, agent-safe metadata
-curl -s http://127.0.0.1:52437/list-services  # names only
-curl -s http://127.0.0.1:52437/status         # full daemon metadata, cached
-```
-
-`/knowledge` returns service names, labels, key types, enabled state, project,
-description, timestamps, and `has_key`. It never returns raw secrets or Vault
-secret names. Use `GET /v/<service>` only for the one exact secret needed by the
-next command. Do not bulk-fetch every service.
+- **Web UI** — unlock vault, manage services, configure mounts
+- **REST API** — `GET /knowledge`, `GET /status`, `GET /v/<service>`, `GET /ping`, `POST /restart`, `GET /shutdown`
+- **MCP server** — Model Context Protocol for Claude Code and claude.ai
+- **Cloudflare Tunnel** — exposes MCP endpoints publicly for claude.ai connectors
+
+Start: `clauth serve start` (starts locked, auto-opens browser for unlock).
+
+Full daemon operations reference: see `regen-root/.claude/rules/clauth.md`.
+
+### Safe Metadata Cache
+
+Agents and scripts must discover services through metadata endpoints, not by
+walking every secret endpoint. The daemon caches service metadata for 30 seconds:
+
+```bash
+curl -s http://127.0.0.1:52437/knowledge      # sanitized, agent-safe metadata
+curl -s http://127.0.0.1:52437/list-services  # names only
+curl -s http://127.0.0.1:52437/status         # full daemon metadata, cached
+```
+
+`/knowledge` returns service names, labels, key types, enabled state, project,
+description, timestamps, and `has_key`. It never returns raw secrets or Vault
+secret names. Use `GET /v/<service>` only for the one exact secret needed by the
+next command. Do not bulk-fetch every service.
 
 ---
 
-## MCP Server — 5 Namespaces, 63 Tools
-
-clauth is the single MCP interface for all local tools. One process, namespaced paths:
-
-| Path | Namespace | Tools | Description |
-|------|-----------|-------|-------------|
-| `/clauth` | `clauth_*` + runtime helpers | 23 | Credential vault operations, safe metadata cache, and agent runtime helpers |
-| `/gws` | `gws_*` | 6 | Google Workspace (Gmail, Calendar, Drive) |
-| `/fs` | `fs_*` | 20 | Filesystem plus guarded git/local-branch tools |
-| `/chitchat` | `chitchat_*` | 7 | Collaboration relay sessions |
-| `/codevelop` | `codevelop_*` | 7 | Peer development sessions |
-| `/mcp` | all | 63 | All namespaces combined (Claude Code) |
-
-The default live `/clauth` surface includes 13 credential tools plus
-`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`
-runtime helpers. Admin write tools such as enable/disable/project/token actions
-are gated by write-mode.
-
-### clauth MCP Usage
-
-Use `clauth_knowledge` or `clauth_status` for discovery. They use cached
-metadata and never retrieve raw secrets. `clauth_search` is metadata-only by
-default; pass `addresses: true` only when you intentionally need redacted address
-hints from connstrings/fileserver/oauth secrets. `clauth_get` is for one exact
-secret. `clauth_inject` refuses more than five services unless `allow_many: true`
-is explicitly supplied, to prevent accidental rate-limit lockouts from bulk
-secret sweeps.
+## MCP Server — 5 Namespaces, 63 Tools
+
+clauth is the single MCP interface for all local tools. One process, namespaced paths:
+
+| Path | Namespace | Tools | Description |
+|------|-----------|-------|-------------|
+| `/clauth` | `clauth_*` + runtime helpers | 23 | Credential vault operations, safe metadata cache, and agent runtime helpers |
+| `/gws` | `gws_*` | 6 | Google Workspace (Gmail, Calendar, Drive) |
+| `/fs` | `fs_*` | 20 | Filesystem plus guarded git/local-branch tools |
+| `/chitchat` | `chitchat_*` | 7 | Collaboration relay sessions |
+| `/codevelop` | `codevelop_*` | 7 | Peer development sessions |
+| `/mcp` | all | 63 | All namespaces combined (Claude Code) |
+
+The default live `/clauth` surface includes 13 credential tools plus
+`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`
+runtime helpers. Admin write tools such as enable/disable/project/token actions
+are gated by write-mode.
+
+### TinTin Agent Setup
+
+clauth owns the local TinTin settings and isolated agent setup contract used by
+app sidebars and the standalone TinTin console.
+
+| Method | Route | Purpose |
+| --- | --- | --- |
+| `GET` | `/tintin/settings` | Read persisted TinTin app/agent/sidebar/dispatch/co-develop settings. |
+| `PUT` | `/tintin/settings` | Save TinTin app/agent/sidebar/dispatch/co-develop settings. |
+| `GET` | `/tintin/settings/ui` | Browser settings page for operators, with sections for Agent Setup, Agent Defaults, Sidebar Apps, Blackboard Dispatch, Co-develop Relay, and stored agent sessions. |
+| `POST` | `/tintin/agent-sessions` | Create or reuse an isolated agent cwd, normally a git worktree. |
+
+The agent-session response includes the requested agent/runtime/model, repo
+root, isolated `cwd`, worktree path, branch, launch mode, and launch command.
+This route prepares the proper Codex/Claude isolation path; separate supervisor
+code is still responsible for long-running process parking and wake/resume.
+
+### clauth MCP Usage
+
+Use `clauth_knowledge` or `clauth_status` for discovery. They use cached
+metadata and never retrieve raw secrets. `clauth_search` is metadata-only by
+default; pass `addresses: true` only when you intentionally need redacted address
+hints from connstrings/fileserver/oauth secrets. `clauth_get` is for one exact
+secret. `clauth_inject` refuses more than five services unless `allow_many: true`
+is explicitly supplied, to prevent accidental rate-limit lockouts from bulk
+secret sweeps.
 
 ### FS Tools
 
-20 filesystem tools with path-jail security:
-- `fs_read`, `fs_write`, `fs_stat`, `fs_append`, `fs_write_chunk`, `fs_ingest_url`, `fs_import_git_files`, `fs_list`, `fs_grep`, `fs_glob`, `fs_delete`, `fs_mkdir`, `fs_edit`, `fs_move`, `fs_copy`, `fs_mounts`, `fs_repo_status`, `fs_use_branch`, `fs_commit`, `fs_diff`
+20 filesystem tools with path-jail security:
+- `fs_read`, `fs_write`, `fs_stat`, `fs_append`, `fs_write_chunk`, `fs_ingest_url`, `fs_import_git_files`, `fs_list`, `fs_grep`, `fs_glob`, `fs_delete`, `fs_mkdir`, `fs_edit`, `fs_move`, `fs_copy`, `fs_mounts`, `fs_repo_status`, `fs_use_branch`, `fs_commit`, `fs_diff`
 - Uses `node:fs/promises` (async), `@vscode/ripgrep` (shipped binary), `fast-glob`
 - Permission flags per mount: `r` (read), `w` (write), `d` (delete)
 - Mount config stored as "fileserver" service type in vault — only configurable through web UI
-- Large writes should use `fs_write_chunk`; cloud-to-local transfer should use `fs_ingest_url`; guarded appends should pass `expected_sha256` from `fs_stat`
-- Durable new files authored by Claude.ai in GitHub should use `fs_import_git_files` so the local dirty monorepo fetches and restores only named paths without `git pull`
-
-### Collaboration Tools
-
-Chitchat tools: `chitchat_start`, `chitchat_list`, `chitchat_send`, `chitchat_recv`, `chitchat_reply`, `chitchat_poll`, `chitchat_stop`
-
-Codevelop tools: `codevelop_start`, `codevelop_join`, `codevelop_send`, `codevelop_poll`, `codevelop_status`, `codevelop_stream`, `codevelop_stop`
-
-### GWS Tools
-
-6 Google Workspace tools: `gws_run`, `gws_gmail_list`, `gws_gmail_read`, `gws_gmail_send`, `gws_calendar_list`, `gws_drive_list`
-- Calls `gws` CLI via `execSync` with `shell: 'bash'` (fixes Windows cmd.exe JSON quoting)
+- Large writes should use `fs_write_chunk`; cloud-to-local transfer should use `fs_ingest_url`; guarded appends should pass `expected_sha256` from `fs_stat`
+- Durable new files authored by Claude.ai in GitHub should use `fs_import_git_files` so the local dirty monorepo fetches and restores only named paths without `git pull`
+
+### Collaboration Tools
+
+Chitchat tools: `chitchat_start`, `chitchat_list`, `chitchat_send`, `chitchat_recv`, `chitchat_reply`, `chitchat_poll`, `chitchat_stop`
+
+Codevelop tools: `codevelop_start`, `codevelop_join`, `codevelop_send`, `codevelop_poll`, `codevelop_status`, `codevelop_stream`, `codevelop_stop`
+
+### GWS Tools
+
+6 Google Workspace tools: `gws_run`, `gws_gmail_list`, `gws_gmail_read`, `gws_gmail_send`, `gws_calendar_list`, `gws_drive_list`
+- Calls `gws` CLI via `execSync` with `shell: 'bash'` (fixes Windows cmd.exe JSON quoting)
 
 ---
 
@@ -235,11 +252,11 @@ Full OAuth 2.1 protocol implementation is present for future use when Anthropic
 
 | Connector | URL |
 |-----------|-----|
-| clauth | `https://clauth.regendevcorp.com/clauth` |
-| gws | `https://clauth.regendevcorp.com/gws` |
-| chitchat | `https://clauth.regendevcorp.com/chitchat` |
-| codevelop | `https://clauth.regendevcorp.com/codevelop` |
-| fs | `https://fs.regendevcorp.com/fs` |
+| clauth | `https://clauth.regendevcorp.com/clauth` |
+| gws | `https://clauth.regendevcorp.com/gws` |
+| chitchat | `https://clauth.regendevcorp.com/chitchat` |
+| codevelop | `https://clauth.regendevcorp.com/codevelop` |
+| fs | `https://fs.regendevcorp.com/fs` |
 
 ---
 
@@ -252,9 +269,9 @@ Full OAuth 2.1 protocol implementation is present for future use when Anthropic
 
 ## Testing
 
-```bash
-node test-tools.mjs    # MCP tool execution smoke tests
-```
+```bash
+node test-tools.mjs    # MCP tool execution smoke tests
+```
 
 Tests actual MCP tool calls (not just OAuth + listing).