Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
feat(skills): split use-avibe references and support Studio review (#1935)
Call Whiteda8763f4269e
diff --git a/core/prompt_studio_catalog.py b/core/prompt_studio_catalog.pyindex 1dc3d6174..551d4bdc6 100644--- a/core/prompt_studio_catalog.py+++ b/core/prompt_studio_catalog.py@@ -6,6 +6,7 @@ import hashlibimport inspectimport jsonimport re+from pathlib import Pathfrom typing import Any, get_type_hintsfrom markdown_it import MarkdownIt@@ -141,9 +142,38 @@ def _skill_documents() -> list[dict[str, Any]]:"blocks": blocks,})+ references = skill_file.parent / "references"+ if references.is_symlink():+ continue+ for reference in sorted(references.rglob("*"), key=lambda path: path.relative_to(references).as_posix()):+ if reference.suffix.lower() != ".md" or reference.is_symlink() or not reference.is_file():+ continue+ if any(parent.is_symlink() for parent in reference.parents if parent != references and references in parent.parents):+ continue+ documents.append(_reference_document(reference, skill_file.parent, skill.name))return documents+def _reference_document(path: Path, skill_directory: Path, skill_name: str) -> dict[str, Any]:+ relative = path.relative_to(skill_directory).as_posix()+ logical_path = f"skills/{skill_directory.name}/{relative}"+ # File identity survives edits and newly added neighboring references. Keep+ # IDs command-safe for the existing Studio translation and review stores.+ identity = f"{skill_name}-ref-{_digest_text(relative)}"+ raw = path.read_text(encoding="utf-8")+ return {+ "id": f"skill-{identity}",+ "name": f"{skill_name} / {relative}",+ "kind": "skill",+ "parent_id": f"skill-{skill_name}",+ "relative_path": relative,+ "source_path": logical_path,+ "description": f"Reference Markdown for {skill_name}.",+ "revision": _digest_text(raw),+ "blocks": _markdown_blocks(raw, id_prefix=identity, first_line=1, source_path=logical_path),+ }++class PromptRenderInputError(ValueError):"""Localized at the CLI boundary; never expose validator exception prose."""diff --git a/docs/plans/prompt-studio.md b/docs/plans/prompt-studio.mdindex d5bc7bae7..d817c5b5c 100644--- a/docs/plans/prompt-studio.md+++ b/docs/plans/prompt-studio.md@@ -14,7 +14,8 @@ The Git checkout is authoritative:- `core/prompt_registry.py` owns stable module identity, ordering, compositionwhitespace, and declared placeholders.- `core/prompts/*.md` owns the English System Prompt prose.-- `skills/*/SKILL.md` owns built-in Skill prose.+- `skills/*/SKILL.md` owns built-in Skill entry prose; `references/**/*.md`+ under each Skill owns its on-demand operating details.- `vibe debug prompt export --format json` is the only supported extractioninterface for Prompt Studio. Consumers do not parse Python source.@@ -23,6 +24,21 @@ Git or choose a branch. A contributor reviews the branch they have checked out.Catalog order and revisions are content-derived and deterministic; the exportcontains no generation timestamp.+Skill references are independent `kind: "skill"` documents immediately after+their entry, ordered by relative path. `parent_id` identifies the owning Skill+document and `relative_path` names the file inside it. Reference document IDs+derive from Skill name and relative path, not contents or directory position.+Each document has its own content revision, source-addressable Markdown blocks,+translation cache, token count, and authored review history. Adding or editing+a reference does not change the entry's revision. Non-Markdown files and symbolic+links are not review documents. Exporting references does not inject them into+the runtime prompt or eagerly load them with the Skill entry.++Moving prose into another file does not rewrite saved reviews: existing authored+blocks remain in the original document's removed-source section and revision+history. A moved file starts its own review identity; migration of authored prose+requires an explicit reviewed save, not an automatic fuzzy match.+The registry defines production composition order, and Studio preserves thatorder without a display-only sort. Each rendered prompt is an ordered subset ofthe complete source catalog, including backend wrappers and optional branches.diff --git a/skills/use-avibe/SKILL.md b/skills/use-avibe/SKILL.mdindex ee00a46ea..a6b4c1970 100644--- a/skills/use-avibe/SKILL.md+++ b/skills/use-avibe/SKILL.md@@ -2,7 +2,7 @@name: use-avibeslug: use-avibedescription: Safely inspect and modify local Avibe configuration, routing, runtime settings, watches, scheduled tasks, Avibe Cloud remote access, and operational state.-version: 0.6.1+version: 0.6.2---# Use Avibe@@ -66,964 +66,24 @@ Use this order when changing Avibe configuration:7. Run `POST /doctor` only when the change affects runtime health, platform credentials, or backend availability.8. Report the changed scope or global keys and whether a restart was avoided or still required.-## Calling the Web UI API+## Task References-Mutating API calls require:+Read only the reference needed for the current task, before composing its calls.+Paths below are relative to this Skill directory; scripts remain under+`scripts/`, not under `references/`.-- same-origin `Origin` or `Referer` header-- CSRF cookie named `vibe_csrf_token`-- matching `X-Vibe-CSRF-Token` header+| Task | Reference |+| --- | --- |+| Send API requests with CSRF, cookies, JSON payloads, or the bundled helper | [API client](references/api-client.md) |+| Change global defaults, platform credentials, proxies, or discover IM channels | [Global configuration and platforms](references/global-config.md) |+| Change channel/DM routing, models, cwd, visibility, mention policy, or bind users | [Scopes and routing](references/scopes-and-routing.md) |+| Pair, inspect, repair, or control the Avibe Cloud tunnel | [Remote access](references/remote-access.md) |+| Run or delegate Agent work, schedule tasks, manage watches or Session queues | [Agent Harness](references/harness.md) |+| Choose backend/subagent settings or change native OpenCode, Claude, or Codex config | [Backends](references/backends.md) |+| Inspect runtime paths, logs, or health; restart or upgrade the service | [Operations and troubleshooting](references/operations.md) |-Use this local curl pattern:--```bash-BASE="http://127.0.0.1:5123"-COOKIE_JAR="$(mktemp)"-CSRF="$(- curl -fsS -c "$COOKIE_JAR" "$BASE/api/csrf-token" \- | python3 -c 'import json,sys; print(json.load(sys.stdin)["csrf_token"])'-)"--curl -fsS -b "$COOKIE_JAR" -c "$COOKIE_JAR" \- -H "Origin: $BASE" \- -H "X-Vibe-CSRF-Token: $CSRF" \- -H "Content-Type: application/json" \- -X POST "$BASE/doctor" \- --data '{}'-```--For `DELETE`, use the same cookie jar, `Origin`, and CSRF header.--When the Web UI is served through Avibe Cloud, the same calls require an authenticated OIDC session cookie issued by `/auth/callback`. Prefer hitting `127.0.0.1:5123` directly from the local machine for maintenance work.--Do not log full request bodies when they contain tokens or secrets.--### Reusable local API helper--For multi-step maintenance, use the bundled helper at `scripts/vibe_api.py` instead of hand-writing curl commands. The helper handles CSRF, same-origin headers, cookies, JSON encoding, and readable error output.--Resolve paths relative to this skill directory. If the skill is installed at `skills/use-avibe`, run:--Usage examples:--```bash-export VIBE_UI_BASE="http://127.0.0.1:5123"--python3 skills/use-avibe/scripts/vibe_api.py GET /health-python3 skills/use-avibe/scripts/vibe_api.py GET '/settings?platform=slack'-python3 skills/use-avibe/scripts/vibe_api.py POST /doctor '{}'-python3 skills/use-avibe/scripts/vibe_api.py POST /config '{"show_duration":true}'-python3 skills/use-avibe/scripts/vibe_api.py DELETE '/api/users/U123?platform=slack'-```--Payload can be passed as inline JSON, as `@payload.json`, or as `-` to read JSON from stdin.--For scope updates, still fetch and merge first:--```bash-API_HELPER="skills/use-avibe/scripts/vibe_api.py"--python3 "$API_HELPER" GET '/settings?platform=slack' > /tmp/slack_settings.json-python3 - <<'PY'-import json-from pathlib import Path--settings = json.loads(Path("/tmp/slack_settings.json").read_text())-channels = settings.get("channels") or {}-channels["C123"] = {- **channels.get("C123", {}),- "enabled": True,- "show_message_types": channels.get("C123", {}).get("show_message_types") or ["assistant"],- "custom_cwd": channels.get("C123", {}).get("custom_cwd"),- "require_mention": channels.get("C123", {}).get("require_mention"),- "routing": {- **(channels.get("C123", {}).get("routing") or {}),- "agent_name": "codex",- "model": "gpt-5.4",- "reasoning_effort": "high",- "codex_model": "gpt-5.4",- "codex_reasoning_effort": "high",- },-}-Path("/tmp/slack_payload.json").write_text(json.dumps({"platform": "slack", "channels": channels}))-PY-python3 "$API_HELPER" POST /settings @/tmp/slack_payload.json-python3 "$API_HELPER" GET '/settings?platform=slack'-```--## Runtime Layout--Avibe stores runtime data under `~/.avibe/` by default, or under `AVIBE_HOME` when that env var is set. Existing default `~/.vibe_remote/` homes may be migrated to `~/.avibe/` with `~/.vibe_remote` kept as a back-symlink. The only paths an agent normally needs:--- `~/.avibe/config/config.json` — global config; mutate through `POST /config`, not by editing the file-- `~/.avibe/logs/vibe_remote.log` — main application log; read via `POST /logs`-- `~/.avibe/screenshots/` — default output directory for `vibe screenshot`-- `~/.avibe/state/user_preferences.md` — shared long-term preference file (safe to read and update)--Agent harness state is managed through `vibe agent run`, `vibe task`, `vibe watch`, and `vibe runs` (or their API endpoints), not by editing persistence files. Everything else under `state/` and `runtime/` is internal — treat it as opaque.--## API Endpoint Reference--### Health and inspection--- `GET /health`- - returns `{"status":"ok"}` when the Web UI server is reachable-- `GET /status`- - returns runtime status, running state, PID metadata, and last action-- `GET /doctor`- - reads the latest persisted doctor result-- `POST /doctor`- - runs doctor immediately and returns the result-- `POST /logs`- - payload: `{"lines": 500, "source": "service"}`- - `source` can be `service` or another source listed in the response; use `all` for aggregated logs-- `GET /version`- - returns current version and update metadata-- `GET /api/csrf-token`- - issues the `vibe_csrf_token` cookie and returns the matching token value for `X-Vibe-CSRF-Token`-- `GET /platforms`- - returns the static catalog of supported IM platforms only (id, config_key, title/description i18n keys, credential field names, capabilities). It does not include enablement or credential-presence state — fetch `/config` to see which platforms are enabled and whether credentials are configured.--### Global config--- `GET /config`- - returns the current V2 config payload-- `POST /config`- - accepts a partial object, deep-merges it with current config, validates it through `V2Config.from_payload`, then persists it- - use for platform credentials, enabled platforms, primary platform, runtime defaults, agent defaults, UI config, remote-access provider settings, update policy, and global toggles- - the handler only persists and (for `remote_access`) reconciles the cloudflared tunnel; running platform adapters keep using their previous credentials and transport until a restart. Plan a `vibe restart --delay-seconds 60` after any credential, `proxy_url`, or transport-level change.--Important config payload shape:--```json-{- "platform": "slack",- "platforms": {- "enabled": ["slack", "discord", "telegram", "lark", "wechat"],- "primary": "slack"- },- "mode": "self_host",- "version": "v2",- "slack": {- "bot_token": "xoxb-...",- "app_token": "xapp-...",- "signing_secret": "...",- "team_id": "T...",- "team_name": "...",- "app_id": "A...",- "require_mention": false,- "disable_link_unfurl": false,- "proxy_url": null- },- "discord": {- "bot_token": "...",- "application_id": "...",- "require_mention": false,- "thread_auto_archive_minutes": 10080,- "guild_allowlist": null,- "guild_denylist": null,- "proxy_url": null- },- "telegram": {- "bot_token": "123:abc",- "require_mention": true,- "forum_auto_topic": true,- "use_webhook": false,- "webhook_url": null,- "webhook_secret_token": null,- "allowed_chat_ids": null,- "allowed_user_ids": null,- "proxy_url": null- },- "lark": {- "app_id": "...",- "app_secret": "...",- "require_mention": false,- "domain": "feishu",- "proxy_url": null- },- "wechat": {- "bot_token": "...",- "base_url": "https://ilinkai.weixin.qq.com",- "cdn_base_url": "https://novac2c.cdn.weixin.qq.com/c2c",- "require_mention": false,- "proxy_url": null- },- "runtime": {- "default_cwd": "/path/to/workdir",- "log_level": "INFO"- },- "agents": {- "opencode": {- "enabled": true,- "cli_path": "opencode",- "default_agent": null,- "default_reasoning_effort": null,- "error_retry_limit": 1- },- "claude": {- "enabled": true,- "cli_path": "claude",- "idle_timeout_seconds": 600- },- "codex": {- "enabled": true,- "cli_path": "codex",- "idle_timeout_seconds": 600- }- },- "ui": {- "setup_host": "127.0.0.1",- "setup_port": 5123,- "open_browser": true- },- "remote_access": {- "provider": "vibe_cloud",- "vibe_cloud": {- "enabled": false,- "backend_url": "https://avibe.bot",- "public_url": "",- "instance_id": "",- "client_id": "",- "issuer": "",- "authorization_endpoint": "",- "token_endpoint": "",- "jwks_uri": "",- "redirect_uri": "",- "tunnel_token": "",- "instance_secret": "",- "session_secret": "",- "cloudflared_path": "",- "transport_protocol": "auto",- "auto_recovery": true,- "optimization_profile": "balanced",- "edge_ip_version": "4",- "edge_bind_address": "",- "dev_login_hint": ""- }- },- "update": {- "auto_update": true,- "check_interval_minutes": 60,- "idle_minutes": 30,- "notify_admins": true- },- "ack_mode": "typing",- "language": "en",- "show_duration": false,- "include_time_info": true,- "include_user_info": true,- "reply_enhancements": true-}-```--Discord server access belongs to `/settings`, not `/config`. Store enabled-servers under `guilds`, next to channel settings:--```json-{- "platform": "discord",- "guilds": {- "900740769198006293": { "enabled": true }- },- "channels": {- "1067738479234138202": { "enabled": true }- }-}-```--When switching the active platform, update `platforms.primary` and make sure `platforms.enabled` contains the new primary. Keep the legacy `platform` field aligned for readability, but `platforms.primary` is the real multi-platform source of truth.--Per-platform fields worth knowing about:--- every platform inherits `proxy_url` from the shared `BaseIMConfig`. Set it when the host machine cannot reach the upstream API directly. Accepts standard HTTP/HTTPS proxy URLs and any `socks*://` URL (`socks4`, `socks4a`, `socks5`, `socks5h`). SOCKS variants route through `aiohttp_socks`.-- `slack.disable_link_unfurl` suppresses link previews when posting messages.-- `discord.thread_auto_archive_minutes` must be one of `60`, `1440`, `4320`, or `10080`.-- `discord.guild_allowlist` / `guild_denylist` are legacy input lists; current runtime server access lives in `/settings` under `guilds`.-- `telegram.forum_auto_topic` enables automatic topic creation in forum chats; `use_webhook` plus `webhook_url` / `webhook_secret_token` switches Telegram delivery to the webhook transport.-- `telegram.allowed_chat_ids` / `allowed_user_ids` restrict which chats and users Telegram will respond to.-- `wechat.cdn_base_url` controls the CDN host used for fetching WeChat media; the default `novac2c.cdn.weixin.qq.com` is the official c2c CDN.-- `update.auto_update`, `check_interval_minutes`, and `idle_minutes` control unattended upgrades; `notify_admins` posts the upgrade announcement to bound admins.-- `ui.setup_host`, `setup_port`, and `open_browser` configure the local Web UI server; changing host or port requires `POST /ui/reload`.--Secret-bearing config fields that you should not print:--- `slack.bot_token`-- `slack.app_token`-- `slack.signing_secret`-- `discord.bot_token`-- `telegram.bot_token`-- `telegram.webhook_secret_token`-- `lark.app_id` (treat as a sensitive identifier)-- `lark.app_secret`-- `wechat.bot_token`-- `gateway.workspace_token`-- `gateway.client_secret`-- `remote_access.vibe_cloud.tunnel_token`-- `remote_access.vibe_cloud.instance_secret`-- `remote_access.vibe_cloud.session_secret`-- `remote_access.vibe_cloud.client_id`-- any `proxy_url` value that embeds credentials such as `user:pass@host`--### Channel settings--- `GET /settings?platform=<platform>`- - returns channel settings, user settings, and bind codes for one platform-- `POST /settings`- - payload: `{"platform": "<platform>", "channels": {...}}`- - validates message visibility and routing, normalizes Claude reasoning, persists the full channel map for that platform--Important: `POST /settings` replaces the entire `channels` map for the selected platform. To change one channel:--1. `GET /settings?platform=<platform>`-2. copy `response.channels`-3. merge or add one channel entry-4. `POST /settings` with the full merged `channels` object-5. `GET /settings?platform=<platform>` again and verify--Channel entry shape:--```json-{- "enabled": true,- "show_message_types": ["assistant"],- "custom_cwd": "/path/to/repo",- "require_mention": null,- "require_bind": null,- "routing": {- "agent_name": "codex",- "model": "gpt-5.4",- "reasoning_effort": "high",- "opencode_agent": null,- "opencode_model": null,- "opencode_reasoning_effort": null,- "claude_agent": null,- "claude_model": null,- "claude_reasoning_effort": null,- "codex_agent": "reviewer",- "codex_model": "gpt-5.4",- "codex_reasoning_effort": "high"- }-}-```--Field meanings:--- `enabled`: whether this channel is allowed to use Avibe-- `show_message_types`: visible intermediate messages; allowed values are `system`, `assistant`, `toolcall`-- `custom_cwd`: scope-level working directory override; empty string or `null` means use global default-- `require_mention`: `null` inherits the platform default, `true` requires mention, `false` disables mention gating for that channel-- `require_bind`: `null`/`false` lets any channel member use the bot (current default); `true` gates the channel to bound users only — messages from unbound senders are silently ignored (no denial reply), while the bot's own replies stay visible to everyone. Enforced in the shared auth pipeline, so it applies on every platform. Bind is platform-wide, so `require_bind` means "is this sender a bound user", not a per-channel allowlist.-- `routing.agent_name`: Vibe Agent name for this scope, or `null` to inherit the default Agent-- `routing.model`: canonical scope-level model override for the selected Agent backend-- `routing.reasoning_effort`: canonical scope-level reasoning override for the selected Agent backend-- `routing.<backend>_agent`: backend-specific subagent-- `routing.<backend>_model` / `routing.<backend>_reasoning_effort`: legacy aliases accepted on input and derived on read-back; do not treat them as independent state--### DM users and bind codes--- `GET /api/users?platform=<platform>`- - returns bound DM users for one platform-- `POST /api/users`- - payload: `{"platform": "<platform>", "users": {...}}`- - merges included users into existing users and preserves each existing user's `dm_chat_id`-- `POST /api/users/<user_id>/admin`- - payload: `{"platform": "<platform>", "is_admin": true}`-- `DELETE /api/users/<user_id>?platform=<platform>`- - removes a bound user; this is the reliable way to revoke DM access-- `GET /api/bind-codes`- - returns all bind codes-- `POST /api/bind-codes`- - payload: `{"type": "one_time"}` or `{"type": "expiring", "expires_at": "2026-04-18"}`-- `DELETE /api/bind-codes/<code>`- - deactivates a bind code-- `GET /api/setup/first-bind-code`- - returns an existing valid setup bind code or creates a new one-time code--Important: user updates are not field patches. Before changing a user's routing, cwd, visibility, or enabled flag, read the current user object and send the merged full user entry.--User entry shape:--```json-{- "display_name": "Alice",- "is_admin": false,- "bound_at": "2026-03-20T12:34:56+00:00",- "enabled": true,- "show_message_types": ["assistant"],- "custom_cwd": "/path/to/repo",- "routing": {- "agent_name": "claude",- "model": "claude-sonnet-4-6",- "reasoning_effort": "high",- "opencode_agent": null,- "opencode_model": null,- "opencode_reasoning_effort": null,- "claude_agent": "reviewer",- "claude_model": "claude-sonnet-4-6",- "claude_reasoning_effort": "high",- "codex_agent": null,- "codex_model": null,- "codex_reasoning_effort": null- }-}-```--DM caveat: current DM authorization checks whether the user is bound, not whether `enabled` is true. If the user wants to revoke DM access, use `DELETE /api/users/<user_id>?platform=<platform>` instead of only setting `enabled` to false.--### Platform discovery and validation--- `GET /slack/manifest`- - returns Slack app manifest JSON for setup-- `POST /slack/auth_test`- - payload: `{"bot_token": "xoxb-..."}`-- `POST /slack/channels`- - payload: `{"bot_token": "xoxb-...", "browse_all": false}`-- `POST /discord/auth_test`- - payload: `{"bot_token": "..."}`-- `POST /discord/guilds`- - payload: `{"bot_token": "..."}`-- `POST /discord/channels`- - payload: `{"bot_token": "...", "guild_id": "..."}`-- `POST /telegram/auth_test`- - payload: `{"bot_token": "123:abc"}`-- `POST /telegram/chats`- - payload: `{"include_private": false}`-- `POST /lark/auth_test`- - payload: `{"app_id": "...", "app_secret": "...", "domain": "feishu"}`-- `POST /lark/chats`- - payload: `{"app_id": "...", "app_secret": "...", "domain": "feishu"}`-- `POST /lark/temp_ws/start`- - payload: `{"app_id": "...", "app_secret": "...", "domain": "feishu"}`-- `POST /lark/temp_ws/stop`- - payload: `{}`-- `POST /wechat/qr_login/start`- - payload: `{"base_url": "https://ilinkai.weixin.qq.com"}` or `{}`-- `POST /wechat/qr_login/poll`- - payload: `{"session_key": "..."}`--WeChat QR login is special: when login is confirmed and a token is returned, the API auto-binds the WeChat user and schedules an internal service restart so the new token can take effect. Do not add an extra restart unless the user asks.--### Remote access (Avibe Cloud)--These endpoints drive the managed `avibe.bot` tunnel that exposes the local Web UI to other devices. They are paired with the `remote_access.vibe_cloud` block under `/config`.--- `GET /api/remote-access/status`- - returns `enabled`, `paired`, `public_url`, `running` (tunnel up), `pid`, `pid_state`, plus `binary_found` / `binary_path` / `binary_version` for the resolved `cloudflared` executable. Use `running: true` to assert the tunnel is up.-- `POST /api/remote-access/vibe-cloud/pair`- - payload: `{"pairing_key": "vrp_..."}`- - exchanges the one-time key for an OIDC client, tunnel token, and persists the full `remote_access.vibe_cloud` block; on success Avibe launches the cloudflared tunnel-- `POST /api/remote-access/start`- - payload: `{}`- - starts the cloudflared tunnel using the persisted pairing config-- `POST /api/remote-access/stop`- - payload: `{}`- - stops the cloudflared tunnel; configuration is preserved so `start` can resume later-- `POST /api/remote-access/optimize-route`- - payload: `{}`- - starts one guarded make-before-break route evaluation; it does not override a pinned protocol-- `GET /api/remote-access/network-interfaces`- - returns currently assigned, up, non-loopback local source addresses that may be selected for cloudflared-- `POST /api/remote-access/settings`- - payload: `{"transport_protocol":"auto|quic|http2","auto_recovery":true,"optimization_profile":"stable|balanced|low_latency","edge_ip_version":"4|auto|6","edge_bind_address":""}`- - applies policy-only changes immediately; Connector-affecting changes start and verify a replacement before draining the previous Connector, and keep the previous persisted settings when the replacement cannot become ready-- `POST /api/remote-access/diagnostics`- - payload: `{}`- - returns bounded DNS, TCP/HTTP2, and observed-active-QUIC reachability without exposing probe targets or local interface addresses-- `GET /auth/callback`- - OIDC redirect target used by avibe.bot during sign-in. Browser-driven; do not call directly from automation.-- `GET /api/session`- - always returns `200` with an auth-state payload, never `401`. Three shapes: `{"remote": false}` when remote access is not configured for this request, `{"remote": true, "authenticated": false}` when remote access is on but the caller has no valid session cookie, and `{"remote": true, "authenticated": true, "email": "..."}` when signed in. Check `authenticated` to gate behavior; do not poll for HTTP status codes.-- `POST /auth/logout`- - clears the avibe.bot session cookie on this device. Does not stop the tunnel.--The session cookie is bound to the tunnel session and expires after roughly 24 hours; the server slides the TTL when activity reaches the half-life. Do not invent custom auth headers — rely on the existing cookie issued by `/auth/callback`.--Treat `tunnel_token`, `instance_secret`, `session_secret`, and `client_id` from `remote_access.vibe_cloud` as opaque secrets.--### Backend and local helper endpoints--- `GET /cli/detect?binary=<name-or-path>`- - detects a CLI binary path-- `POST /agent/<name>/install`- - `name` must be `opencode`, `claude`, or `codex`-- `POST /opencode/options`- - payload: `{"cwd": "/path/to/repo"}`- - returns OpenCode model, agent, and reasoning option data for that cwd-- `POST /opencode/setup-permission`- - intentionally writes OpenCode native config to set `permission` to `allow`-- `GET /claude/agents?cwd=/path/to/repo`-- `GET /codex/agents?cwd=/path/to/repo`-- `GET /claude/models`-- `GET /codex/models`-- `POST /browse`- - payload: `{"path": "~", "show_hidden": false}`--### Control endpoints--- `POST /control`- - payload: `{"action": "start"}`, `{"action": "stop"}`, or `{"action": "restart"}`-- `POST /ui/reload`- - payload: `{"host": "127.0.0.1", "port": 5123}`-- `POST /upgrade`- - payload: `{}`- - triggers an in-place upgrade to the latest released version using the same code path as `vibe upgrade`--Avoid these for routine configuration. `POST /control` starts, stops, or restarts the service. `POST /ui/reload` restarts only the Web UI server to apply host or port changes. `POST /upgrade` reinstalls Avibe and then restarts the service. Use them only with explicit user intent or a concrete need.--When the restart is initiated by an agent from an active conversation, use the CLI delayed form `vibe restart --delay-seconds 60` so the transport does not cut off the current reply.--## Scope and Precedence Rules--### Agent selection--Agent resolution priority is:--1. existing Agent Session backend snapshot, when the message belongs to an existing session/thread-2. scope-level `routing.agent_name` from `/settings` or `/api/users`, for new sessions-3. global default Vibe Agent from the Agent catalog-4. registered backend compatibility fallback, only when no enabled default Agent is available--If the user names a specific channel or DM and wants a specific Agent, use the scope API, not global `/config`. New routing is Agent-based.--### Working directory--Working directory resolution is:--1. `custom_cwd` on the target channel or user scope-2. `runtime.default_cwd` from `/config`--### Message visibility--`show_message_types` is scope-local. Preserve existing values unless the user wants an explicit replacement.--If a user asks for "vault messages", "internal messages", or "tool execution messages", map that request to `show_message_types`. Current Avibe does not expose a separate `vault` field.--### Mention policy--`require_mention` works like this:--- `null`: inherit platform default from `/config`-- `true`: require mention in that channel-- `false`: do not require mention in that channel--## Recipes--### Route one Slack channel to Codex--Goal:--- enable Slack channel `C123`-- route it to Codex-- use Codex subagent `reviewer`-- use model `gpt-5.4`-- set reasoning `high`--API flow:--1. `GET /settings?platform=slack`-2. merge `channels.C123`-3. `POST /settings` with all Slack channels-4. read back `GET /settings?platform=slack`--Merged channel entry:--```json-{- "enabled": true,- "show_message_types": ["assistant"],- "custom_cwd": null,- "require_mention": null,- "routing": {- "agent_name": "codex",- "model": "gpt-5.4",- "reasoning_effort": "high",- "opencode_agent": null,- "opencode_model": null,- "opencode_reasoning_effort": null,- "claude_agent": null,- "claude_model": null,- "claude_reasoning_effort": null,- "codex_agent": "reviewer",- "codex_model": "gpt-5.4",- "codex_reasoning_effort": "high"- }-}-```--### Route one channel to OpenCode with a subagent--Use `/settings` and set:--- `routing.agent_name = "opencode"`-- `routing.opencode_agent = "<agent>"`-- `routing.model = "<model>"` if requested-- `routing.reasoning_effort = "<effort>"` if requested--If the user wants OpenCode-native defaults, providers, MCP servers, skills, plugins, or API credentials, use OpenCode config instead of Avibe scope routing.--### Route one scope to Claude with model and reasoning--Use `/settings` for a channel or `/api/users` for a DM user and set:--- `routing.agent_name = "claude"`-- `routing.claude_agent = "<agent>"` if requested-- `routing.model = "<model>"`-- `routing.reasoning_effort = "<effort>"`--The API normalizes Claude reasoning for incompatible model combinations; verify by reading back the saved payload.--### Change the global default working directory--Use `POST /config`:--```json-{- "runtime": {- "default_cwd": "/path/to/workdir"- }-}-```--Do not overwrite scope-level `custom_cwd` entries.--### Show tool execution messages in one channel--Use `/settings` and add `toolcall` to the target channel's `show_message_types`.--Preserve existing `system` and `assistant` values unless the user asked for a full replacement.--### Switch primary platform--Use `POST /config` and keep `platforms.enabled` complete:--```json-{- "platform": "discord",- "platforms": {- "enabled": ["slack", "discord"],- "primary": "discord"- }-}-```--Make sure the target platform config section exists and validates. Do not delete old platform config unless the user explicitly asks.--### Configure an outbound proxy for an IM platform--When the host cannot reach a platform API directly, set `proxy_url` on that platform's config block.--Use `POST /config` with only the proxy field for the affected platform:--```json-{- "telegram": {- "proxy_url": "http://proxy.internal:3128"- }-}-```--Notes:--- `proxy_url` accepts `http://`, `https://`, and any `socks*://` scheme (`socks4`, `socks4a`, `socks5`, `socks5h`). The SOCKS variants route through `aiohttp_socks` (bundled).-- Set the field to `null` (or omit it on a fresh save) to disable the proxy.-- `POST /config` only persists the new value; running platform adapters keep their old transport until the service restarts. After saving, run `vibe restart --delay-seconds 60` (or `POST /control {"action":"restart"}` with the user's confirmation) so the proxy applies to live connections.-- Do not paste credentialed proxy URLs (`user:pass@host`) into logs or chat replies; mask the credentials portion when reporting back.--### Pair Avibe Cloud remote access--Goal: connect the local Web UI to `avibe.bot` so it is reachable from another device.--1. The user signs in at `https://avibe.bot`, creates a remote-access bot, and copies the one-time pairing key (format `vrp_...`).-2. Call `POST /remote-access/vibe-cloud/pair` with `{"pairing_key": "vrp_..."}` from the local Web UI origin.-3. Verify with `GET /remote-access/status` — `enabled: true`, `paired: true`, `public_url` populated, `running: true`.-4. Have the user open `public_url` and sign in with the same avibe.bot account.--Alternatively, drive the same flow from the CLI:--```bash-vibe remote # guided flow-vibe remote pair vrp_abc123 # paste key directly-vibe remote status --json # inspect tunnel state-vibe remote stop # stop tunnel; keep config-vibe remote start # bring tunnel back up-```--Treat the pairing key, tunnel token, instance secret, and session secret as opaque. Never echo them in chat replies.--### Generate a DM bind code--Use `POST /api/bind-codes`:--```json-{- "type": "one_time"-}-```--For an expiring code:--```json-{- "type": "expiring",- "expires_at": "2026-04-18"-}-```--Do not expose bind codes unless the user explicitly asks for them.--## Agent Harness: Runs, Tasks, and Watches--Use the harness commands when the user wants an agent to leave the current turn and continue later, repeatedly, or in the background. The mental model is:--- `vibe agent run`: run one concrete Agent job now. Runs are async by default; pass `--sync` only when the current CLI must wait for the result.-- `vibe task`: save a time trigger that creates Agent Runs later-- `vibe watch`: save a condition trigger that waits for a process, file, log, CI, review, or other signal, then creates a follow-up Agent Run-- `vibe runs`: inspect and cancel concrete run records--Agents should prefer these managed harness commands over ad-hoc detached shells when the work should be inspectable, resumable, or report back to the conversation.--Preferred CLI shape:--- delegate to another Agent in a private/background Session from an Avibe Agent shell: `vibe agent run --agent '<agent-name>' --message '...'`-- delegate to a visible sibling Session in the same scope from an Avibe Agent shell: `vibe agent run --agent '<agent-name>' --same-scope --message '...'`-- wait for an Agent result in the terminal: `vibe agent run --sync --agent '<agent-name>' --message '...'`-- continue a specific existing Session: `vibe agent run --session-id '<session-id>' --message '...'`-- explicitly steer a new message as P1 into the active Turn: `vibe agent run --session-id '<session-id>' --send-now --message '...'`-- steer an already-queued exact head without adding a message: `vibe session send-now '<session-id>'`-- inspect another Session's durable FIFO queue: `vibe session queue list '<session-id>'`-- remove one exact queued message after inspecting its stable ID: `vibe session queue remove '<session-id>' '<message-id>'`-- fork this Session for an alternate path: `vibe agent run --fork-self --message '...'`-- fork another explicit Session for an alternate path: `vibe agent run --fork-session '<source-session-id>' --message '...'`-- recurring task for this conversation: `vibe task add --cron '<expr>' --message '...'`-- one-off task for this conversation: `vibe task add --at '<ISO-8601>' --message '...'`-- task that creates a visible sibling Session: `vibe task add --create-session --same-scope --cron '<expr>' --message '...'`-- scheduled command with no Agent turn: `vibe task add --cron '<expr>' --shell '<command>'`-- command task with AI failure triage: `vibe task add --cron '<expr>' --shell '<command>' --on-failure agent --message '<what to do>'`-- immediate rerun: `vibe task run <id>`-- managed background watch for this conversation: `vibe watch add --message '...' -- <cmd>` (or `--shell '<cmd>'` to pass a single shell string)-- watch that creates a visible sibling Session: `vibe watch add --create-session --same-scope --message '...' -- <cmd>`-- update a watch: `vibe watch update <id> --name '...' --timeout 1200`-- inspect a run: `vibe runs show <run-id>`-- cancel a run: `vibe runs cancel <run-id>`--Targeting and callbacks:--- In an Avibe-injected Agent shell, commands that operate on this conversation default to the current Agent Session. Omit the target when the work should continue here.-- Use `--session-id <id>` only when the command should operate on a different existing Agent Session.-- When `vibe agent run --session-id <id>` targets an existing Session, it sends a new message into that Session. It does not change that Session's cwd, scope, Agent, model, or reasoning settings.-- When coordinating another Workbench Session, decide whether its current turn should finish or be preempted from the work dependency, urgency, and cost of discarding in-flight work. An explicit user request is one signal, not a prerequisite.-- Add `--send-now` to explicitly select the normal content-bearing P1 behavior for an existing Session. It steers that new message into an active Turn, starts it when idle, and falls back to P3 only after a definitive refusal; it never promotes an older queued message.-- Use `vibe session send-now <session-id>` when a Session already has queued work and no new message should be added. This promotes the existing FIFO head.-- Both commands use the shared steering path for Workbench and IM Sessions. A refused or stale steer leaves the affected input durably queued and never falls back to Stop.-- Use `vibe session queue list <session-id>` before changing another Workbench Session's queue. If an instruction is obsolete, contradictory, or duplicated, remove that exact stable row with `vibe session queue remove <session-id> <message-id>`. Never guess a message ID or delete another row to simulate reordering.-- When `vibe agent run` creates a new Session, the default placement is private/background. Add `--same-scope` for a visible sibling Session in the same Workbench project or IM scope, or `--scope-id <scopes.id>` for a specific existing scope.-- When a task, watch, or new Agent run creates a Session and `--cwd` is omitted, Avibe uses the command's current working directory. Forks keep the source Session cwd by default.-- Async Agent runs return the final result to this conversation by default. Pass `--no-callback` only when you will inspect the run later with `vibe runs`. Pass `--callback-session-id <id>` only when the final result should return to a different Session.-- `--message` and `--message-file` are the user-message flags for task, watch, and agent-run commands.-- `vibe task add` stores a message template — or, with `--shell` / a trailing `-- <argv>`, a command — and creates Runs when the time trigger fires. A command task runs with no Agent turn: silent on success, a failure notice on failure, `--on-failure agent` to escalate failures to an Agent.-- `vibe watch add` uses `--message` as the instruction template for the Agent Run created after the waiter reaches a reportable state.-- `--fork-self` forks this Session's native backend context. `--fork-session <id>` forks another explicit Session. Forks keep the source Session backend, scope, and cwd by default.-- Fork overrides are intentionally narrow: `--agent`, `--model`, and `--reasoning-effort` can override the forked Session only if the backend stays the same. Do not combine fork flags with existing-session or session-creation flags.--Operational guidance:--- use `vibe task list` before editing or deleting an existing task; use `vibe watch list` before touching a managed watch-- if this is the first time using `vibe task add`, `vibe agent run`, `vibe runs`, or `vibe watch add`, read the matching `--help` output first — watches and command tasks both accept `--shell` and `--timeout` (per-cycle for watches, per-run for tasks), while `--lifetime-timeout` (overall), `--forever`, `--retry-exit-code`, and `--retry-delay` stay watch-only-- for Watch waiters, exit `0` means one new reportable event; an allowed retry exit code keeps either mode waiting, while `64` plus `avibe-watch: no-event` ends a once Watch or re-arms a forever Watch without an Agent Run; a once waiter that is still waiting must use a retry exit code-- a forever waiter must keep a durable cursor, state transition, or domain cooldown; Avibe serializes its event follow-ups and automatically pauses plus sends a repair Run after six successful events within 60 seconds-- use `vibe task update <id>` to keep the same task ID while changing name, schedule, message, agent, or target-- use `vibe watch update <id> ...` when you must rename, retarget, or change the waiter/options-- Agent-facing collection commands return 20 compact rows per page, cap `--limit` at 100, and have no unpaginated `--all` mode; follow `pagination.next_command` when more rows exist-- read task/watch records from `definition` for detail commands and `definitions` for list commands; command-specific duplicate aliases are not emitted-- use `--include-finished` for paginated task/watch one-shot history-- both list commands hide successful one-shot definitions by default while failures stay visible; use `--include-finished` and follow `pagination.next_command` for bounded history-- use `vibe task show <id>`, `vibe watch show <id>`, or `vibe runs show <run-id>` to inspect stored fields and runtime state-- use `vibe task pause` / `vibe task resume` and `vibe watch pause` / `vibe watch resume` to disable a task or watch without deleting it-- treat `warnings` from task, watch, agent-run, or runs commands as delivery-risk hints to fix proactively--## Agent Backend Capability Matrix--Current Avibe Agent capabilities are:--| Backend | Select through Vibe Agent | Subagent | Model | Reasoning |-| --- | --- | --- | --- | --- |-| OpenCode | yes | yes | yes | yes |-| Claude | yes | yes | yes | yes |-| Codex | yes | yes | yes | yes |--Behavior notes:--- OpenCode subagents are selected through `routing.opencode_agent` or through prefix routing such as `reviewer: ...`.-- Claude subagents are selected through `routing.claude_agent` or prefix routing.-- Codex subagents are selected through `routing.codex_agent` or prefix routing.-- Claude reasoning is selected through `routing.claude_reasoning_effort`; common values are `low`, `medium`, and `high`, and some models also allow `max`.-- If a Claude reasoning value is invalid for the chosen model, the API normalizes or drops that override and falls back to the backend default.--## Subagent and Prefix Routing--If the user asks for subagents, remember:--- OpenCode, Claude, and Codex support prefix-triggered subagent selection like `planner: draft a migration plan`-- when a subagent definition provides its own default model or reasoning setting, that subagent-level value overrides the channel default-- Claude subagents are discovered from markdown files under:- - `~/.claude/agents/`- - project `.claude/agents/`-- Codex custom agents are discovered from TOML files under:- - `~/.codex/agents/`- - project `.codex/agents/`-- OpenCode subagent and model defaults come from the OpenCode runtime/config rather than only from Avibe's own config--## Host Backend Guidance--When the request belongs to the host backend, do not force it into Avibe config.--### OpenCode--Use OpenCode-native config when the user wants to change:--- personal default model-- global reasoning behavior-- provider and API keys-- MCP servers-- skills, plugins, tools, or project-local OpenCode behavior--Important locations:--- `~/.config/opencode/opencode.json`: global OpenCode config-- project `opencode.json`: project-level OpenCode config file-- `.opencode/`: project-local OpenCode config directory-- `~/.config/opencode/agents/`: global OpenCode agents-- `.opencode/agents/`: project-local OpenCode agents-- `~/.config/opencode/skills/`: global OpenCode skills-- `.opencode/skills/`: project-local OpenCode skills--Relevant docs:--- config: `https://opencode.ai/docs/config/`-- skills: `https://opencode.ai/docs/skills`-- plugins: `https://opencode.ai/docs/plugins/`-- MCP servers: `https://opencode.ai/docs/mcp-servers/`--Inside Avibe, a scope can select an OpenCode-backed Vibe Agent and then set subagent, model, and reasoning effort overrides. Use `POST /opencode/setup-permission` only for the specific permission helper.--### Claude Code--Use Claude-native config when the user wants to change:--- Claude subagent definitions-- Claude skills-- CLAUDE instructions and project rules--Important locations:--- `~/.claude/agents/`: global Claude subagents-- `.claude/agents/`: project subagents-- `~/.claude/skills/`: global Claude skills-- `.claude/skills/`: project skills--Relevant docs:--- subagents: `https://docs.anthropic.com/en/docs/claude-code/sub-agents`--Inside Avibe, a scope can select a Claude-backed Vibe Agent and then set model, subagent, and reasoning effort overrides.--### Codex--Use Codex-native config when the user wants to change:--- personal default model-- global reasoning defaults-- MCP servers, approvals, or sandbox policy-- Codex CLI profiles and behavior outside Avibe--Important locations:--- `~/.codex/config.toml`: global Codex config-- `.codex/config.toml`: project-local Codex config-- `~/.codex/agents/`: global Codex custom agents-- `.codex/agents/`: project-local Codex custom agents--Relevant docs:--- config basics: `https://developers.openai.com/codex/config-basic/`-- config reference: `https://developers.openai.com/codex/config-reference/`-- CLI overview: `https://developers.openai.com/codex/cli`-- subagents: `https://developers.openai.com/codex/subagents`--Inside Avibe, a scope can select a Codex-backed Vibe Agent and then set subagent, model, and reasoning effort overrides.--## CLI Reference--Use the CLI only when the Web UI API cannot cover the request, when the user explicitly asks for the command, or when restarting/upgrading from an active conversation.--Service lifecycle:--- `vibe` — start Avibe if needed and open the local Web UI; it does not stop an already-running service-- `vibe status` — print service status, PID metadata, and last action-- `vibe stop` — stop main service, Web UI, and any background helpers-- `vibe restart` — stop and re-start the service. Pass `--delay-seconds N` when triggering from inside an active conversation so the current reply has time to deliver before the restart lands.-- `vibe doctor` — run diagnostics and print the latest result-- `vibe version` — print the installed version--Updates:--- `vibe check-update` — query the release feed and print whether an upgrade is available-- `vibe upgrade` — reinstall Avibe to the latest release. The CLI does not restart the service for you; it prints "Please restart vibe..." and exits. Run `vibe restart` (or `vibe restart --delay-seconds 60` from inside an active conversation) yourself after the upgrade reports success. The Web UI's `POST /upgrade` endpoint is the path that performs an automatic restart.--Remote access:--- `vibe remote` — guided Avibe Cloud pairing-- `vibe remote pair <key>` — pair using an existing one-time key-- `vibe remote status [--json]` — show tunnel + OIDC state-- `vibe remote start` / `vibe remote stop` — manage the cloudflared tunnel after pairing--Screenshots:--- `vibe screenshot` — capture the local desktop to `~/.avibe/screenshots/`-- `vibe screenshot --output <path>` / `--json` — pick an explicit output path or get machine-readable output--Scheduled tasks:--- `vibe task add`, `vibe task update`, `vibe task list [--include-finished] [--page N] [--limit N]`, `vibe task show <id>`, `vibe task run <id>`, `vibe task pause <id>`, `vibe task resume <id>`, `vibe task remove <id>`-- Switching a task between message and command form, or changing `--on-failure`, is rejected — remove and recreate.--Agent runs:--- `vibe agent run` — run one Agent job now. Runs are async by default; pass `--sync` only when the CLI should wait.-- `vibe runs list`, `vibe runs show <id>`, `vibe runs cancel <id>` — inspect and manage concrete Agent Run records--Watches:--- `vibe watch add`, `vibe watch update <id>`, `vibe watch list [--include-finished] [--page N] [--limit N]`, `vibe watch show <id>`, `vibe watch pause <id>`, `vibe watch resume <id>`, `vibe watch remove <id>`--For any subcommand, prefer `<command> --help` before composing a new invocation. Harness commands default to this Agent Session inside an Avibe-injected Agent shell. Use `--session-id` only to target a different existing Session, `--same-scope` or `--scope-id` when creating a Session in a visible scope, and `--no-callback` only when an async Agent run will be inspected later through `vibe runs`. Use `--message` / `--message-file` for user messages. `vibe task add` and `vibe watch add` take `--name`; only `vibe task add` takes `--cron` / `--at` / `--timezone`; `vibe agent run` takes `--sync`; and `vibe watch add` takes its own waiter options (`--shell` or a positional command after `--`, `--cwd`, `--timeout`, `--forever`, `--lifetime-timeout`, `--retry-exit-code`, `--retry-delay`). `vibe task add` also accepts `--shell` or a command after `--`, plus `--on-failure {none,agent}` and a per-run `--timeout`; a pure command task takes no session, scope, or agent flags. Do not copy flags between task, watch, and agent-run commands without checking help.--## Troubleshooting--Start with evidence:--1. `GET /status`-2. `POST /doctor`-3. `POST /logs` with a small line count and focused source-4. read back `/config`, `/settings`, or `/api/users` for the affected scope--Common cases:--- config does not apply: verify the API read-back first; only restart if the changed field is startup-only-- backend missing: confirm backend is enabled, CLI path is executable, and `/cli/detect` finds it-- channel does not respond: verify `/settings?platform=<platform>` contains the channel and `enabled` is true-- wrong repository/cwd: inspect `custom_cwd` and `runtime.default_cwd`-- DM access denied: inspect `/api/users?platform=<platform>` and bind-code state-- platform cannot reach API: inspect `proxy_url` on that platform's config block; check logs for proxy/TLS errors; for SOCKS proxies confirm `aiohttp_socks` is installed-- remote URL is unreachable: `GET /remote-access/status` should show `running: true` and `binary_found: true`; if not, run `POST /doctor` and check the configured `cloudflared_path`-- remote session expired: instruct the user to re-sign in at the public URL (24h TTL with sliding renewal); use `POST /auth/logout` to clear a stale session on the current device-- upgrade did not apply: inspect the response from `POST /upgrade` (auto-restart on success) or `vibe upgrade` (does not auto-restart — run `vibe restart` manually), then verify with `vibe status` that the new PID is running-- startup failure: use `GET /status`, `POST /doctor`, then inspect logs--Do not use `vibe restart`, `POST /control {"action":"restart"}`, or `POST /ui/reload` as a first response to config problems.--If a restart is still required and you are replying through an active Avibe conversation, use `vibe restart --delay-seconds 60` so the current reply can be delivered before the restart lands.+For multi-step API work, use the bundled `scripts/vibe_api.py` helper.+The API client reference contains its exact invocations and fetch/merge examples.## Safety Boundariesdiff --git a/skills/use-avibe/references/api-client.md b/skills/use-avibe/references/api-client.mdnew file mode 100644index 000000000..a17c421ef--- /dev/null+++ b/skills/use-avibe/references/api-client.md@@ -0,0 +1,86 @@+# API Client++## Calling the Web UI API++Mutating API calls require:++- same-origin `Origin` or `Referer` header+- CSRF cookie named `vibe_csrf_token`+- matching `X-Vibe-CSRF-Token` header++Use this local curl pattern:++```bash+BASE="http://127.0.0.1:5123"+COOKIE_JAR="$(mktemp)"+CSRF="$(+ curl -fsS -c "$COOKIE_JAR" "$BASE/api/csrf-token" \+ | python3 -c 'import json,sys; print(json.load(sys.stdin)["csrf_token"])'+)"++curl -fsS -b "$COOKIE_JAR" -c "$COOKIE_JAR" \+ -H "Origin: $BASE" \+ -H "X-Vibe-CSRF-Token: $CSRF" \+ -H "Content-Type: application/json" \+ -X POST "$BASE/doctor" \+ --data '{}'+```++For `DELETE`, use the same cookie jar, `Origin`, and CSRF header.++When the Web UI is served through Avibe Cloud, the same calls require an authenticated OIDC session cookie issued by `/auth/callback`. Prefer hitting `127.0.0.1:5123` directly from the local machine for maintenance work.++Do not log full request bodies when they contain tokens or secrets.++### Reusable local API helper++For multi-step maintenance, use the bundled helper at `scripts/vibe_api.py` instead of hand-writing curl commands. The helper handles CSRF, same-origin headers, cookies, JSON encoding, and readable error output.++Resolve paths relative to this skill directory. If the skill is installed at `skills/use-avibe`, run:++Usage examples:++```bash+export VIBE_UI_BASE="http://127.0.0.1:5123"++python3 skills/use-avibe/scripts/vibe_api.py GET /health+python3 skills/use-avibe/scripts/vibe_api.py GET '/settings?platform=slack'+python3 skills/use-avibe/scripts/vibe_api.py POST /doctor '{}'+python3 skills/use-avibe/scripts/vibe_api.py POST /config '{"show_duration":true}'+python3 skills/use-avibe/scripts/vibe_api.py DELETE '/api/users/U123?platform=slack'+```++Payload can be passed as inline JSON, as `@payload.json`, or as `-` to read JSON from stdin.++For scope updates, still fetch and merge first:++```bash+API_HELPER="skills/use-avibe/scripts/vibe_api.py"++python3 "$API_HELPER" GET '/settings?platform=slack' > /tmp/slack_settings.json+python3 - <<'PY'+import json+from pathlib import Path++settings = json.loads(Path("/tmp/slack_settings.json").read_text())+channels = settings.get("channels") or {}+channels["C123"] = {+ **channels.get("C123", {}),+ "enabled": True,+ "show_message_types": channels.get("C123", {}).get("show_message_types") or ["assistant"],+ "custom_cwd": channels.get("C123", {}).get("custom_cwd"),+ "require_mention": channels.get("C123", {}).get("require_mention"),+ "routing": {+ **(channels.get("C123", {}).get("routing") or {}),+ "agent_name": "codex",+ "model": "gpt-5.4",+ "reasoning_effort": "high",+ "codex_model": "gpt-5.4",+ "codex_reasoning_effort": "high",+ },+}+Path("/tmp/slack_payload.json").write_text(json.dumps({"platform": "slack", "channels": channels}))+PY+python3 "$API_HELPER" POST /settings @/tmp/slack_payload.json+python3 "$API_HELPER" GET '/settings?platform=slack'+```diff --git a/skills/use-avibe/references/backends.md b/skills/use-avibe/references/backends.mdnew file mode 100644index 000000000..bd7c35b1a--- /dev/null+++ b/skills/use-avibe/references/backends.md@@ -0,0 +1,130 @@+# Backend Configuration++### Backend and local helper endpoints++- `GET /cli/detect?binary=<name-or-path>`+ - detects a CLI binary path+- `POST /agent/<name>/install`+ - `name` must be `opencode`, `claude`, or `codex`+- `POST /opencode/options`+ - payload: `{"cwd": "/path/to/repo"}`+ - returns OpenCode model, agent, and reasoning option data for that cwd+- `POST /opencode/setup-permission`+ - intentionally writes OpenCode native config to set `permission` to `allow`+- `GET /claude/agents?cwd=/path/to/repo`+- `GET /codex/agents?cwd=/path/to/repo`+- `GET /claude/models`+- `GET /codex/models`+- `POST /browse`+ - payload: `{"path": "~", "show_hidden": false}`++## Agent Backend Capability Matrix++Current Avibe Agent capabilities are:++| Backend | Select through Vibe Agent | Subagent | Model | Reasoning |+| --- | --- | --- | --- | --- |+| OpenCode | yes | yes | yes | yes |+| Claude | yes | yes | yes | yes |+| Codex | yes | yes | yes | yes |++Behavior notes:++- OpenCode subagents are selected through `routing.opencode_agent` or through prefix routing such as `reviewer: ...`.+- Claude subagents are selected through `routing.claude_agent` or prefix routing.+- Codex subagents are selected through `routing.codex_agent` or prefix routing.+- Claude reasoning is selected through `routing.claude_reasoning_effort`; common values are `low`, `medium`, and `high`, and some models also allow `max`.+- If a Claude reasoning value is invalid for the chosen model, the API normalizes or drops that override and falls back to the backend default.++## Subagent and Prefix Routing++If the user asks for subagents, remember:++- OpenCode, Claude, and Codex support prefix-triggered subagent selection like `planner: draft a migration plan`+- when a subagent definition provides its own default model or reasoning setting, that subagent-level value overrides the channel default+- Claude subagents are discovered from markdown files under:+ - `~/.claude/agents/`+ - project `.claude/agents/`+- Codex custom agents are discovered from TOML files under:+ - `~/.codex/agents/`+ - project `.codex/agents/`+- OpenCode subagent and model defaults come from the OpenCode runtime/config rather than only from Avibe's own config++## Host Backend Guidance++When the request belongs to the host backend, do not force it into Avibe config.++### OpenCode++Use OpenCode-native config when the user wants to change:++- personal default model+- global reasoning behavior+- provider and API keys+- MCP servers+- skills, plugins, tools, or project-local OpenCode behavior++Important locations:++- `~/.config/opencode/opencode.json`: global OpenCode config+- project `opencode.json`: project-level OpenCode config file+- `.opencode/`: project-local OpenCode config directory+- `~/.config/opencode/agents/`: global OpenCode agents+- `.opencode/agents/`: project-local OpenCode agents+- `~/.config/opencode/skills/`: global OpenCode skills+- `.opencode/skills/`: project-local OpenCode skills++Relevant docs:++- config: `https://opencode.ai/docs/config/`+- skills: `https://opencode.ai/docs/skills`+- plugins: `https://opencode.ai/docs/plugins/`+- MCP servers: `https://opencode.ai/docs/mcp-servers/`++Inside Avibe, a scope can select an OpenCode-backed Vibe Agent and then set subagent, model, and reasoning effort overrides. Use `POST /opencode/setup-permission` only for the specific permission helper.++### Claude Code++Use Claude-native config when the user wants to change:++- Claude subagent definitions+- Claude skills+- CLAUDE instructions and project rules++Important locations:++- `~/.claude/agents/`: global Claude subagents+- `.claude/agents/`: project subagents+- `~/.claude/skills/`: global Claude skills+- `.claude/skills/`: project skills++Relevant docs:++- subagents: `https://docs.anthropic.com/en/docs/claude-code/sub-agents`++Inside Avibe, a scope can select a Claude-backed Vibe Agent and then set model, subagent, and reasoning effort overrides.++### Codex++Use Codex-native config when the user wants to change:++- personal default model+- global reasoning defaults+- MCP servers, approvals, or sandbox policy+- Codex CLI profiles and behavior outside Avibe++Important locations:++- `~/.codex/config.toml`: global Codex config+- `.codex/config.toml`: project-local Codex config+- `~/.codex/agents/`: global Codex custom agents+- `.codex/agents/`: project-local Codex custom agents++Relevant docs:++- config basics: `https://developers.openai.com/codex/config-basic/`+- config reference: `https://developers.openai.com/codex/config-reference/`+- CLI overview: `https://developers.openai.com/codex/cli`+- subagents: `https://developers.openai.com/codex/subagents`++Inside Avibe, a scope can select a Codex-backed Vibe Agent and then set subagent, model, and reasoning effort overrides.diff --git a/skills/use-avibe/references/global-config.md b/skills/use-avibe/references/global-config.mdnew file mode 100644index 000000000..2882bac2c--- /dev/null+++ b/skills/use-avibe/references/global-config.md@@ -0,0 +1,266 @@+# Global Configuration and Platforms++### Global config++- `GET /config`+ - returns the current V2 config payload+- `POST /config`+ - accepts a partial object, deep-merges it with current config, validates it through `V2Config.from_payload`, then persists it+ - use for platform credentials, enabled platforms, primary platform, runtime defaults, agent defaults, UI config, remote-access provider settings, update policy, and global toggles+ - the handler only persists and (for `remote_access`) reconciles the cloudflared tunnel; running platform adapters keep using their previous credentials and transport until a restart. Plan a `vibe restart --delay-seconds 60` after any credential, `proxy_url`, or transport-level change.++Important config payload shape:++```json+{+ "platform": "slack",+ "platforms": {+ "enabled": ["slack", "discord", "telegram", "lark", "wechat"],+ "primary": "slack"+ },+ "mode": "self_host",+ "version": "v2",+ "slack": {+ "bot_token": "xoxb-...",+ "app_token": "xapp-...",+ "signing_secret": "...",+ "team_id": "T...",+ "team_name": "...",+ "app_id": "A...",+ "require_mention": false,+ "disable_link_unfurl": false,+ "proxy_url": null+ },+ "discord": {+ "bot_token": "...",+ "application_id": "...",+ "require_mention": false,+ "thread_auto_archive_minutes": 10080,+ "guild_allowlist": null,+ "guild_denylist": null,+ "proxy_url": null+ },+ "telegram": {+ "bot_token": "123:abc",+ "require_mention": true,+ "forum_auto_topic": true,+ "use_webhook": false,+ "webhook_url": null,+ "webhook_secret_token": null,+ "allowed_chat_ids": null,+ "allowed_user_ids": null,+ "proxy_url": null+ },+ "lark": {+ "app_id": "...",+ "app_secret": "...",+ "require_mention": false,+ "domain": "feishu",+ "proxy_url": null+ },+ "wechat": {+ "bot_token": "...",+ "base_url": "https://ilinkai.weixin.qq.com",+ "cdn_base_url": "https://novac2c.cdn.weixin.qq.com/c2c",+ "require_mention": false,+ "proxy_url": null+ },+ "runtime": {+ "default_cwd": "/path/to/workdir",+ "log_level": "INFO"+ },+ "agents": {+ "opencode": {+ "enabled": true,+ "cli_path": "opencode",+ "default_agent": null,+ "default_reasoning_effort": null,+ "error_retry_limit": 1+ },+ "claude": {+ "enabled": true,+ "cli_path": "claude",+ "idle_timeout_seconds": 600+ },+ "codex": {+ "enabled": true,+ "cli_path": "codex",+ "idle_timeout_seconds": 600+ }+ },+ "ui": {+ "setup_host": "127.0.0.1",+ "setup_port": 5123,+ "open_browser": true+ },+ "remote_access": {+ "provider": "vibe_cloud",+ "vibe_cloud": {+ "enabled": false,+ "backend_url": "https://avibe.bot",+ "public_url": "",+ "instance_id": "",+ "client_id": "",+ "issuer": "",+ "authorization_endpoint": "",+ "token_endpoint": "",+ "jwks_uri": "",+ "redirect_uri": "",+ "tunnel_token": "",+ "instance_secret": "",+ "session_secret": "",+ "cloudflared_path": "",+ "transport_protocol": "auto",+ "auto_recovery": true,+ "optimization_profile": "balanced",+ "edge_ip_version": "4",+ "edge_bind_address": "",+ "dev_login_hint": ""+ }+ },+ "update": {+ "auto_update": true,+ "check_interval_minutes": 60,+ "idle_minutes": 30,+ "notify_admins": true+ },+ "ack_mode": "typing",+ "language": "en",+ "show_duration": false,+ "include_time_info": true,+ "include_user_info": true,+ "reply_enhancements": true+}+```++Discord server access belongs to `/settings`, not `/config`. Store enabled+servers under `guilds`, next to channel settings:++```json+{+ "platform": "discord",+ "guilds": {+ "900740769198006293": { "enabled": true }+ },+ "channels": {+ "1067738479234138202": { "enabled": true }+ }+}+```++When switching the active platform, update `platforms.primary` and make sure `platforms.enabled` contains the new primary. Keep the legacy `platform` field aligned for readability, but `platforms.primary` is the real multi-platform source of truth.++Per-platform fields worth knowing about:++- every platform inherits `proxy_url` from the shared `BaseIMConfig`. Set it when the host machine cannot reach the upstream API directly. Accepts standard HTTP/HTTPS proxy URLs and any `socks*://` URL (`socks4`, `socks4a`, `socks5`, `socks5h`). SOCKS variants route through `aiohttp_socks`.+- `slack.disable_link_unfurl` suppresses link previews when posting messages.+- `discord.thread_auto_archive_minutes` must be one of `60`, `1440`, `4320`, or `10080`.+- `discord.guild_allowlist` / `guild_denylist` are legacy input lists; current runtime server access lives in `/settings` under `guilds`.+- `telegram.forum_auto_topic` enables automatic topic creation in forum chats; `use_webhook` plus `webhook_url` / `webhook_secret_token` switches Telegram delivery to the webhook transport.+- `telegram.allowed_chat_ids` / `allowed_user_ids` restrict which chats and users Telegram will respond to.+- `wechat.cdn_base_url` controls the CDN host used for fetching WeChat media; the default `novac2c.cdn.weixin.qq.com` is the official c2c CDN.+- `update.auto_update`, `check_interval_minutes`, and `idle_minutes` control unattended upgrades; `notify_admins` posts the upgrade announcement to bound admins.+- `ui.setup_host`, `setup_port`, and `open_browser` configure the local Web UI server; changing host or port requires `POST /ui/reload`.++Secret-bearing config fields that you should not print:++- `slack.bot_token`+- `slack.app_token`+- `slack.signing_secret`+- `discord.bot_token`+- `telegram.bot_token`+- `telegram.webhook_secret_token`+- `lark.app_id` (treat as a sensitive identifier)+- `lark.app_secret`+- `wechat.bot_token`+- `gateway.workspace_token`+- `gateway.client_secret`+- `remote_access.vibe_cloud.tunnel_token`+- `remote_access.vibe_cloud.instance_secret`+- `remote_access.vibe_cloud.session_secret`+- `remote_access.vibe_cloud.client_id`+- any `proxy_url` value that embeds credentials such as `user:pass@host`++### Platform discovery and validation++- `GET /slack/manifest`+ - returns Slack app manifest JSON for setup+- `POST /slack/auth_test`+ - payload: `{"bot_token": "xoxb-..."}`+- `POST /slack/channels`+ - payload: `{"bot_token": "xoxb-...", "browse_all": false}`+- `POST /discord/auth_test`+ - payload: `{"bot_token": "..."}`+- `POST /discord/guilds`+ - payload: `{"bot_token": "..."}`+- `POST /discord/channels`+ - payload: `{"bot_token": "...", "guild_id": "..."}`+- `POST /telegram/auth_test`+ - payload: `{"bot_token": "123:abc"}`+- `POST /telegram/chats`+ - payload: `{"include_private": false}`+- `POST /lark/auth_test`+ - payload: `{"app_id": "...", "app_secret": "...", "domain": "feishu"}`+- `POST /lark/chats`+ - payload: `{"app_id": "...", "app_secret": "...", "domain": "feishu"}`+- `POST /lark/temp_ws/start`+ - payload: `{"app_id": "...", "app_secret": "...", "domain": "feishu"}`+- `POST /lark/temp_ws/stop`+ - payload: `{}`+- `POST /wechat/qr_login/start`+ - payload: `{"base_url": "https://ilinkai.weixin.qq.com"}` or `{}`+- `POST /wechat/qr_login/poll`+ - payload: `{"session_key": "..."}`++WeChat QR login is special: when login is confirmed and a token is returned, the API auto-binds the WeChat user and schedules an internal service restart so the new token can take effect. Do not add an extra restart unless the user asks.++### Change the global default working directory++Use `POST /config`:++```json+{+ "runtime": {+ "default_cwd": "/path/to/workdir"+ }+}+```++Do not overwrite scope-level `custom_cwd` entries.++### Switch primary platform++Use `POST /config` and keep `platforms.enabled` complete:++```json+{+ "platform": "discord",+ "platforms": {+ "enabled": ["slack", "discord"],+ "primary": "discord"+ }+}+```++Make sure the target platform config section exists and validates. Do not delete old platform config unless the user explicitly asks.++### Configure an outbound proxy for an IM platform++When the host cannot reach a platform API directly, set `proxy_url` on that platform's config block.++Use `POST /config` with only the proxy field for the affected platform:++```json+{+ "telegram": {+ "proxy_url": "http://proxy.internal:3128"+ }+}+```++Notes:++- `proxy_url` accepts `http://`, `https://`, and any `socks*://` scheme (`socks4`, `socks4a`, `socks5`, `socks5h`). The SOCKS variants route through `aiohttp_socks` (bundled).+- Set the field to `null` (or omit it on a fresh save) to disable the proxy.+- `POST /config` only persists the new value; running platform adapters keep their old transport until the service restarts. After saving, run `vibe restart --delay-seconds 60` (or `POST /control {"action":"restart"}` with the user's confirmation) so the proxy applies to live connections.+- Do not paste credentialed proxy URLs (`user:pass@host`) into logs or chat replies; mask the credentials portion when reporting back.diff --git a/skills/use-avibe/references/harness.md b/skills/use-avibe/references/harness.mdnew file mode 100644index 000000000..2e8f8a5d8--- /dev/null+++ b/skills/use-avibe/references/harness.md@@ -0,0 +1,69 @@+## Agent Harness: Runs, Tasks, and Watches++Use the harness commands when the user wants an agent to leave the current turn and continue later, repeatedly, or in the background. The mental model is:++- `vibe agent run`: run one concrete Agent job now. Runs are async by default; pass `--sync` only when the current CLI must wait for the result.+- `vibe task`: save a time trigger that creates Agent Runs later+- `vibe watch`: save a condition trigger that waits for a process, file, log, CI, review, or other signal, then creates a follow-up Agent Run+- `vibe runs`: inspect and cancel concrete run records++Agents should prefer these managed harness commands over ad-hoc detached shells when the work should be inspectable, resumable, or report back to the conversation.++Preferred CLI shape:++- delegate to another Agent in a private/background Session from an Avibe Agent shell: `vibe agent run --agent '<agent-name>' --message '...'`+- delegate to a visible sibling Session in the same scope from an Avibe Agent shell: `vibe agent run --agent '<agent-name>' --same-scope --message '...'`+- wait for an Agent result in the terminal: `vibe agent run --sync --agent '<agent-name>' --message '...'`+- continue a specific existing Session: `vibe agent run --session-id '<session-id>' --message '...'`+- explicitly steer a new message as P1 into the active Turn: `vibe agent run --session-id '<session-id>' --send-now --message '...'`+- steer an already-queued exact head without adding a message: `vibe session send-now '<session-id>'`+- inspect another Session's durable FIFO queue: `vibe session queue list '<session-id>'`+- remove one exact queued message after inspecting its stable ID: `vibe session queue remove '<session-id>' '<message-id>'`+- fork this Session for an alternate path: `vibe agent run --fork-self --message '...'`+- fork another explicit Session for an alternate path: `vibe agent run --fork-session '<source-session-id>' --message '...'`+- recurring task for this conversation: `vibe task add --cron '<expr>' --message '...'`+- one-off task for this conversation: `vibe task add --at '<ISO-8601>' --message '...'`+- task that creates a visible sibling Session: `vibe task add --create-session --same-scope --cron '<expr>' --message '...'`+- scheduled command with no Agent turn: `vibe task add --cron '<expr>' --shell '<command>'`+- command task with AI failure triage: `vibe task add --cron '<expr>' --shell '<command>' --on-failure agent --message '<what to do>'`+- immediate rerun: `vibe task run <id>`+- managed background watch for this conversation: `vibe watch add --message '...' -- <cmd>` (or `--shell '<cmd>'` to pass a single shell string)+- watch that creates a visible sibling Session: `vibe watch add --create-session --same-scope --message '...' -- <cmd>`+- update a watch: `vibe watch update <id> --name '...' --timeout 1200`+- inspect a run: `vibe runs show <run-id>`+- cancel a run: `vibe runs cancel <run-id>`++Targeting and callbacks:++- In an Avibe-injected Agent shell, commands that operate on this conversation default to the current Agent Session. Omit the target when the work should continue here.+- Use `--session-id <id>` only when the command should operate on a different existing Agent Session.+- When `vibe agent run --session-id <id>` targets an existing Session, it sends a new message into that Session. It does not change that Session's cwd, scope, Agent, model, or reasoning settings.+- When coordinating another Workbench Session, decide whether its current turn should finish or be preempted from the work dependency, urgency, and cost of discarding in-flight work. An explicit user request is one signal, not a prerequisite.+- Add `--send-now` to explicitly select the normal content-bearing P1 behavior for an existing Session. It steers that new message into an active Turn, starts it when idle, and falls back to P3 only after a definitive refusal; it never promotes an older queued message.+- Use `vibe session send-now <session-id>` when a Session already has queued work and no new message should be added. This promotes the existing FIFO head.+- Both commands use the shared steering path for Workbench and IM Sessions. A refused or stale steer leaves the affected input durably queued and never falls back to Stop.+- Use `vibe session queue list <session-id>` before changing another Workbench Session's queue. If an instruction is obsolete, contradictory, or duplicated, remove that exact stable row with `vibe session queue remove <session-id> <message-id>`. Never guess a message ID or delete another row to simulate reordering.+- When `vibe agent run` creates a new Session, the default placement is private/background. Add `--same-scope` for a visible sibling Session in the same Workbench project or IM scope, or `--scope-id <scopes.id>` for a specific existing scope.+- When a task, watch, or new Agent run creates a Session and `--cwd` is omitted, Avibe uses the command's current working directory. Forks keep the source Session cwd by default.+- Async Agent runs return the final result to this conversation by default. Pass `--no-callback` only when you will inspect the run later with `vibe runs`. Pass `--callback-session-id <id>` only when the final result should return to a different Session.+- `--message` and `--message-file` are the user-message flags for task, watch, and agent-run commands.+- `vibe task add` stores a message template — or, with `--shell` / a trailing `-- <argv>`, a command — and creates Runs when the time trigger fires. A command task runs with no Agent turn: silent on success, a failure notice on failure, `--on-failure agent` to escalate failures to an Agent.+- `vibe watch add` uses `--message` as the instruction template for the Agent Run created after the waiter reaches a reportable state.+- `--fork-self` forks this Session's native backend context. `--fork-session <id>` forks another explicit Session. Forks keep the source Session backend, scope, and cwd by default.+- Fork overrides are intentionally narrow: `--agent`, `--model`, and `--reasoning-effort` can override the forked Session only if the backend stays the same. Do not combine fork flags with existing-session or session-creation flags.++Operational guidance:++- use `vibe task list` before editing or deleting an existing task; use `vibe watch list` before touching a managed watch+- if this is the first time using `vibe task add`, `vibe agent run`, `vibe runs`, or `vibe watch add`, read the matching `--help` output first — watches and command tasks both accept `--shell` and `--timeout` (per-cycle for watches, per-run for tasks), while `--lifetime-timeout` (overall), `--forever`, `--retry-exit-code`, and `--retry-delay` stay watch-only+- for Watch waiters, exit `0` means one new reportable event; an allowed retry exit code keeps either mode waiting, while `64` plus `avibe-watch: no-event` ends a once Watch or re-arms a forever Watch without an Agent Run; a once waiter that is still waiting must use a retry exit code+- a forever waiter must keep a durable cursor, state transition, or domain cooldown; Avibe serializes its event follow-ups and automatically pauses plus sends a repair Run after six successful events within 60 seconds+- use `vibe task update <id>` to keep the same task ID while changing name, schedule, message, agent, or target+- use `vibe watch update <id> ...` when you must rename, retarget, or change the waiter/options+- Agent-facing collection commands return 20 compact rows per page, cap `--limit` at 100, and have no unpaginated `--all` mode; follow `pagination.next_command` when more rows exist+- read task/watch records from `definition` for detail commands and `definitions` for list commands; command-specific duplicate aliases are not emitted+- use `--include-finished` for paginated task/watch one-shot history+- both list commands hide successful one-shot definitions by default while failures stay visible; use `--include-finished` and follow `pagination.next_command` for bounded history+- use `vibe task show <id>`, `vibe watch show <id>`, or `vibe runs show <run-id>` to inspect stored fields and runtime state+- use `vibe task pause` / `vibe task resume` and `vibe watch pause` / `vibe watch resume` to disable a task or watch without deleting it+- treat `warnings` from task, watch, agent-run, or runs commands as delivery-risk hints to fix proactivelydiff --git a/skills/use-avibe/references/operations.md b/skills/use-avibe/references/operations.mdnew file mode 100644index 000000000..81d74a4de--- /dev/null+++ b/skills/use-avibe/references/operations.md@@ -0,0 +1,120 @@+# Service Operations and Troubleshooting++## Runtime Layout++Avibe stores runtime data under `~/.avibe/` by default, or under `AVIBE_HOME` when that env var is set. Existing default `~/.vibe_remote/` homes may be migrated to `~/.avibe/` with `~/.vibe_remote` kept as a back-symlink. The only paths an agent normally needs:++- `~/.avibe/config/config.json` — global config; mutate through `POST /config`, not by editing the file+- `~/.avibe/logs/vibe_remote.log` — main application log; read via `POST /logs`+- `~/.avibe/screenshots/` — default output directory for `vibe screenshot`+- `~/.avibe/state/user_preferences.md` — shared long-term preference file (safe to read and update)++Agent harness state is managed through `vibe agent run`, `vibe task`, `vibe watch`, and `vibe runs` (or their API endpoints), not by editing persistence files. Everything else under `state/` and `runtime/` is internal — treat it as opaque.++## API Endpoint Reference++### Health and inspection++- `GET /health`+ - returns `{"status":"ok"}` when the Web UI server is reachable+- `GET /status`+ - returns runtime status, running state, PID metadata, and last action+- `GET /doctor`+ - reads the latest persisted doctor result+- `POST /doctor`+ - runs doctor immediately and returns the result+- `POST /logs`+ - payload: `{"lines": 500, "source": "service"}`+ - `source` can be `service` or another source listed in the response; use `all` for aggregated logs+- `GET /version`+ - returns current version and update metadata+- `GET /api/csrf-token`+ - issues the `vibe_csrf_token` cookie and returns the matching token value for `X-Vibe-CSRF-Token`+- `GET /platforms`+ - returns the static catalog of supported IM platforms only (id, config_key, title/description i18n keys, credential field names, capabilities). It does not include enablement or credential-presence state — fetch `/config` to see which platforms are enabled and whether credentials are configured.++### Control endpoints++- `POST /control`+ - payload: `{"action": "start"}`, `{"action": "stop"}`, or `{"action": "restart"}`+- `POST /ui/reload`+ - payload: `{"host": "127.0.0.1", "port": 5123}`+- `POST /upgrade`+ - payload: `{}`+ - triggers an in-place upgrade to the latest released version using the same code path as `vibe upgrade`++Avoid these for routine configuration. `POST /control` starts, stops, or restarts the service. `POST /ui/reload` restarts only the Web UI server to apply host or port changes. `POST /upgrade` reinstalls Avibe and then restarts the service. Use them only with explicit user intent or a concrete need.++When the restart is initiated by an agent from an active conversation, use the CLI delayed form `vibe restart --delay-seconds 60` so the transport does not cut off the current reply.++## CLI Reference++Use the CLI only when the Web UI API cannot cover the request, when the user explicitly asks for the command, or when restarting/upgrading from an active conversation.++Service lifecycle:++- `vibe` — start Avibe if needed and open the local Web UI; it does not stop an already-running service+- `vibe status` — print service status, PID metadata, and last action+- `vibe stop` — stop main service, Web UI, and any background helpers+- `vibe restart` — stop and re-start the service. Pass `--delay-seconds N` when triggering from inside an active conversation so the current reply has time to deliver before the restart lands.+- `vibe doctor` — run diagnostics and print the latest result+- `vibe version` — print the installed version++Updates:++- `vibe check-update` — query the release feed and print whether an upgrade is available+- `vibe upgrade` — reinstall Avibe to the latest release. The CLI does not restart the service for you; it prints "Please restart vibe..." and exits. Run `vibe restart` (or `vibe restart --delay-seconds 60` from inside an active conversation) yourself after the upgrade reports success. The Web UI's `POST /upgrade` endpoint is the path that performs an automatic restart.++Remote access:++- `vibe remote` — guided Avibe Cloud pairing+- `vibe remote pair <key>` — pair using an existing one-time key+- `vibe remote status [--json]` — show tunnel + OIDC state+- `vibe remote start` / `vibe remote stop` — manage the cloudflared tunnel after pairing++Screenshots:++- `vibe screenshot` — capture the local desktop to `~/.avibe/screenshots/`+- `vibe screenshot --output <path>` / `--json` — pick an explicit output path or get machine-readable output++Scheduled tasks:++- `vibe task add`, `vibe task update`, `vibe task list [--include-finished] [--page N] [--limit N]`, `vibe task show <id>`, `vibe task run <id>`, `vibe task pause <id>`, `vibe task resume <id>`, `vibe task remove <id>`+- Switching a task between message and command form, or changing `--on-failure`, is rejected — remove and recreate.++Agent runs:++- `vibe agent run` — run one Agent job now. Runs are async by default; pass `--sync` only when the CLI should wait.+- `vibe runs list`, `vibe runs show <id>`, `vibe runs cancel <id>` — inspect and manage concrete Agent Run records++Watches:++- `vibe watch add`, `vibe watch update <id>`, `vibe watch list [--include-finished] [--page N] [--limit N]`, `vibe watch show <id>`, `vibe watch pause <id>`, `vibe watch resume <id>`, `vibe watch remove <id>`++For any subcommand, prefer `<command> --help` before composing a new invocation. Harness commands default to this Agent Session inside an Avibe-injected Agent shell. Use `--session-id` only to target a different existing Session, `--same-scope` or `--scope-id` when creating a Session in a visible scope, and `--no-callback` only when an async Agent run will be inspected later through `vibe runs`. Use `--message` / `--message-file` for user messages. `vibe task add` and `vibe watch add` take `--name`; only `vibe task add` takes `--cron` / `--at` / `--timezone`; `vibe agent run` takes `--sync`; and `vibe watch add` takes its own waiter options (`--shell` or a positional command after `--`, `--cwd`, `--timeout`, `--forever`, `--lifetime-timeout`, `--retry-exit-code`, `--retry-delay`). `vibe task add` also accepts `--shell` or a command after `--`, plus `--on-failure {none,agent}` and a per-run `--timeout`; a pure command task takes no session, scope, or agent flags. Do not copy flags between task, watch, and agent-run commands without checking help.++## Troubleshooting++Start with evidence:++1. `GET /status`+2. `POST /doctor`+3. `POST /logs` with a small line count and focused source+4. read back `/config`, `/settings`, or `/api/users` for the affected scope++Common cases:++- config does not apply: verify the API read-back first; only restart if the changed field is startup-only+- backend missing: confirm backend is enabled, CLI path is executable, and `/cli/detect` finds it+- channel does not respond: verify `/settings?platform=<platform>` contains the channel and `enabled` is true+- wrong repository/cwd: inspect `custom_cwd` and `runtime.default_cwd`+- DM access denied: inspect `/api/users?platform=<platform>` and bind-code state+- platform cannot reach API: inspect `proxy_url` on that platform's config block; check logs for proxy/TLS errors; for SOCKS proxies confirm `aiohttp_socks` is installed+- remote URL is unreachable: `GET /remote-access/status` should show `running: true` and `binary_found: true`; if not, run `POST /doctor` and check the configured `cloudflared_path`+- remote session expired: instruct the user to re-sign in at the public URL (24h TTL with sliding renewal); use `POST /auth/logout` to clear a stale session on the current device+- upgrade did not apply: inspect the response from `POST /upgrade` (auto-restart on success) or `vibe upgrade` (does not auto-restart — run `vibe restart` manually), then verify with `vibe status` that the new PID is running+- startup failure: use `GET /status`, `POST /doctor`, then inspect logs++Do not use `vibe restart`, `POST /control {"action":"restart"}`, or `POST /ui/reload` as a first response to config problems.++If a restart is still required and you are replying through an active Avibe conversation, use `vibe restart --delay-seconds 60` so the current reply can be delivered before the restart lands.diff --git a/skills/use-avibe/references/remote-access.md b/skills/use-avibe/references/remote-access.mdnew file mode 100644index 000000000..9084ba18a--- /dev/null+++ b/skills/use-avibe/references/remote-access.md@@ -0,0 +1,59 @@+# Avibe Cloud Remote Access++### Remote access (Avibe Cloud)++These endpoints drive the managed `avibe.bot` tunnel that exposes the local Web UI to other devices. They are paired with the `remote_access.vibe_cloud` block under `/config`.++- `GET /api/remote-access/status`+ - returns `enabled`, `paired`, `public_url`, `running` (tunnel up), `pid`, `pid_state`, plus `binary_found` / `binary_path` / `binary_version` for the resolved `cloudflared` executable. Use `running: true` to assert the tunnel is up.+- `POST /api/remote-access/vibe-cloud/pair`+ - payload: `{"pairing_key": "vrp_..."}`+ - exchanges the one-time key for an OIDC client, tunnel token, and persists the full `remote_access.vibe_cloud` block; on success Avibe launches the cloudflared tunnel+- `POST /api/remote-access/start`+ - payload: `{}`+ - starts the cloudflared tunnel using the persisted pairing config+- `POST /api/remote-access/stop`+ - payload: `{}`+ - stops the cloudflared tunnel; configuration is preserved so `start` can resume later+- `POST /api/remote-access/optimize-route`+ - payload: `{}`+ - starts one guarded make-before-break route evaluation; it does not override a pinned protocol+- `GET /api/remote-access/network-interfaces`+ - returns currently assigned, up, non-loopback local source addresses that may be selected for cloudflared+- `POST /api/remote-access/settings`+ - payload: `{"transport_protocol":"auto|quic|http2","auto_recovery":true,"optimization_profile":"stable|balanced|low_latency","edge_ip_version":"4|auto|6","edge_bind_address":""}`+ - applies policy-only changes immediately; Connector-affecting changes start and verify a replacement before draining the previous Connector, and keep the previous persisted settings when the replacement cannot become ready+- `POST /api/remote-access/diagnostics`+ - payload: `{}`+ - returns bounded DNS, TCP/HTTP2, and observed-active-QUIC reachability without exposing probe targets or local interface addresses+- `GET /auth/callback`+ - OIDC redirect target used by avibe.bot during sign-in. Browser-driven; do not call directly from automation.+- `GET /api/session`+ - always returns `200` with an auth-state payload, never `401`. Three shapes: `{"remote": false}` when remote access is not configured for this request, `{"remote": true, "authenticated": false}` when remote access is on but the caller has no valid session cookie, and `{"remote": true, "authenticated": true, "email": "..."}` when signed in. Check `authenticated` to gate behavior; do not poll for HTTP status codes.+- `POST /auth/logout`+ - clears the avibe.bot session cookie on this device. Does not stop the tunnel.++The session cookie is bound to the tunnel session and expires after roughly 24 hours; the server slides the TTL when activity reaches the half-life. Do not invent custom auth headers — rely on the existing cookie issued by `/auth/callback`.++Treat `tunnel_token`, `instance_secret`, `session_secret`, and `client_id` from `remote_access.vibe_cloud` as opaque secrets.++### Pair Avibe Cloud remote access++Goal: connect the local Web UI to `avibe.bot` so it is reachable from another device.++1. The user signs in at `https://avibe.bot`, creates a remote-access bot, and copies the one-time pairing key (format `vrp_...`).+2. Call `POST /remote-access/vibe-cloud/pair` with `{"pairing_key": "vrp_..."}` from the local Web UI origin.+3. Verify with `GET /remote-access/status` — `enabled: true`, `paired: true`, `public_url` populated, `running: true`.+4. Have the user open `public_url` and sign in with the same avibe.bot account.++Alternatively, drive the same flow from the CLI:++```bash+vibe remote # guided flow+vibe remote pair vrp_abc123 # paste key directly+vibe remote status --json # inspect tunnel state+vibe remote stop # stop tunnel; keep config+vibe remote start # bring tunnel back up+```++Treat the pairing key, tunnel token, instance secret, and session secret as opaque. Never echo them in chat replies.diff --git a/skills/use-avibe/references/scopes-and-routing.md b/skills/use-avibe/references/scopes-and-routing.mdnew file mode 100644index 000000000..b39eb8661--- /dev/null+++ b/skills/use-avibe/references/scopes-and-routing.md@@ -0,0 +1,234 @@+# Channels, Users, and Routing++### Channel settings++- `GET /settings?platform=<platform>`+ - returns channel settings, user settings, and bind codes for one platform+- `POST /settings`+ - payload: `{"platform": "<platform>", "channels": {...}}`+ - validates message visibility and routing, normalizes Claude reasoning, persists the full channel map for that platform++Important: `POST /settings` replaces the entire `channels` map for the selected platform. To change one channel:++1. `GET /settings?platform=<platform>`+2. copy `response.channels`+3. merge or add one channel entry+4. `POST /settings` with the full merged `channels` object+5. `GET /settings?platform=<platform>` again and verify++Channel entry shape:++```json+{+ "enabled": true,+ "show_message_types": ["assistant"],+ "custom_cwd": "/path/to/repo",+ "require_mention": null,+ "require_bind": null,+ "routing": {+ "agent_name": "codex",+ "model": "gpt-5.4",+ "reasoning_effort": "high",+ "opencode_agent": null,+ "opencode_model": null,+ "opencode_reasoning_effort": null,+ "claude_agent": null,+ "claude_model": null,+ "claude_reasoning_effort": null,+ "codex_agent": "reviewer",+ "codex_model": "gpt-5.4",+ "codex_reasoning_effort": "high"+ }+}+```++Field meanings:++- `enabled`: whether this channel is allowed to use Avibe+- `show_message_types`: visible intermediate messages; allowed values are `system`, `assistant`, `toolcall`+- `custom_cwd`: scope-level working directory override; empty string or `null` means use global default+- `require_mention`: `null` inherits the platform default, `true` requires mention, `false` disables mention gating for that channel+- `require_bind`: `null`/`false` lets any channel member use the bot (current default); `true` gates the channel to bound users only — messages from unbound senders are silently ignored (no denial reply), while the bot's own replies stay visible to everyone. Enforced in the shared auth pipeline, so it applies on every platform. Bind is platform-wide, so `require_bind` means "is this sender a bound user", not a per-channel allowlist.+- `routing.agent_name`: Vibe Agent name for this scope, or `null` to inherit the default Agent+- `routing.model`: canonical scope-level model override for the selected Agent backend+- `routing.reasoning_effort`: canonical scope-level reasoning override for the selected Agent backend+- `routing.<backend>_agent`: backend-specific subagent+- `routing.<backend>_model` / `routing.<backend>_reasoning_effort`: legacy aliases accepted on input and derived on read-back; do not treat them as independent state++### DM users and bind codes++- `GET /api/users?platform=<platform>`+ - returns bound DM users for one platform+- `POST /api/users`+ - payload: `{"platform": "<platform>", "users": {...}}`+ - merges included users into existing users and preserves each existing user's `dm_chat_id`+- `POST /api/users/<user_id>/admin`+ - payload: `{"platform": "<platform>", "is_admin": true}`+- `DELETE /api/users/<user_id>?platform=<platform>`+ - removes a bound user; this is the reliable way to revoke DM access+- `GET /api/bind-codes`+ - returns all bind codes+- `POST /api/bind-codes`+ - payload: `{"type": "one_time"}` or `{"type": "expiring", "expires_at": "2026-04-18"}`+- `DELETE /api/bind-codes/<code>`+ - deactivates a bind code+- `GET /api/setup/first-bind-code`+ - returns an existing valid setup bind code or creates a new one-time code++Important: user updates are not field patches. Before changing a user's routing, cwd, visibility, or enabled flag, read the current user object and send the merged full user entry.++User entry shape:++```json+{+ "display_name": "Alice",+ "is_admin": false,+ "bound_at": "2026-03-20T12:34:56+00:00",+ "enabled": true,+ "show_message_types": ["assistant"],+ "custom_cwd": "/path/to/repo",+ "routing": {+ "agent_name": "claude",+ "model": "claude-sonnet-4-6",+ "reasoning_effort": "high",+ "opencode_agent": null,+ "opencode_model": null,+ "opencode_reasoning_effort": null,+ "claude_agent": "reviewer",+ "claude_model": "claude-sonnet-4-6",+ "claude_reasoning_effort": "high",+ "codex_agent": null,+ "codex_model": null,+ "codex_reasoning_effort": null+ }+}+```++DM caveat: current DM authorization checks whether the user is bound, not whether `enabled` is true. If the user wants to revoke DM access, use `DELETE /api/users/<user_id>?platform=<platform>` instead of only setting `enabled` to false.++## Scope and Precedence Rules++### Agent selection++Agent resolution priority is:++1. existing Agent Session backend snapshot, when the message belongs to an existing session/thread+2. scope-level `routing.agent_name` from `/settings` or `/api/users`, for new sessions+3. global default Vibe Agent from the Agent catalog+4. registered backend compatibility fallback, only when no enabled default Agent is available++If the user names a specific channel or DM and wants a specific Agent, use the scope API, not global `/config`. New routing is Agent-based.++### Working directory++Working directory resolution is:++1. `custom_cwd` on the target channel or user scope+2. `runtime.default_cwd` from `/config`++### Message visibility++`show_message_types` is scope-local. Preserve existing values unless the user wants an explicit replacement.++If a user asks for "vault messages", "internal messages", or "tool execution messages", map that request to `show_message_types`. Current Avibe does not expose a separate `vault` field.++### Mention policy++`require_mention` works like this:++- `null`: inherit platform default from `/config`+- `true`: require mention in that channel+- `false`: do not require mention in that channel++## Recipes++### Route one Slack channel to Codex++Goal:++- enable Slack channel `C123`+- route it to Codex+- use Codex subagent `reviewer`+- use model `gpt-5.4`+- set reasoning `high`++API flow:++1. `GET /settings?platform=slack`+2. merge `channels.C123`+3. `POST /settings` with all Slack channels+4. read back `GET /settings?platform=slack`++Merged channel entry:++```json+{+ "enabled": true,+ "show_message_types": ["assistant"],+ "custom_cwd": null,+ "require_mention": null,+ "routing": {+ "agent_name": "codex",+ "model": "gpt-5.4",+ "reasoning_effort": "high",+ "opencode_agent": null,+ "opencode_model": null,+ "opencode_reasoning_effort": null,+ "claude_agent": null,+ "claude_model": null,+ "claude_reasoning_effort": null,+ "codex_agent": "reviewer",+ "codex_model": "gpt-5.4",+ "codex_reasoning_effort": "high"+ }+}+```++### Route one channel to OpenCode with a subagent++Use `/settings` and set:++- `routing.agent_name = "opencode"`+- `routing.opencode_agent = "<agent>"`+- `routing.model = "<model>"` if requested+- `routing.reasoning_effort = "<effort>"` if requested++If the user wants OpenCode-native defaults, providers, MCP servers, skills, plugins, or API credentials, use OpenCode config instead of Avibe scope routing.++### Route one scope to Claude with model and reasoning++Use `/settings` for a channel or `/api/users` for a DM user and set:++- `routing.agent_name = "claude"`+- `routing.claude_agent = "<agent>"` if requested+- `routing.model = "<model>"`+- `routing.reasoning_effort = "<effort>"`++The API normalizes Claude reasoning for incompatible model combinations; verify by reading back the saved payload.++### Show tool execution messages in one channel++Use `/settings` and add `toolcall` to the target channel's `show_message_types`.++Preserve existing `system` and `assistant` values unless the user asked for a full replacement.++### Generate a DM bind code++Use `POST /api/bind-codes`:++```json+{+ "type": "one_time"+}+```++For an expiring code:++```json+{+ "type": "expiring",+ "expires_at": "2026-04-18"+}+```++Do not expose bind codes unless the user explicitly asks for them.diff --git a/tests/test_harness_skill_guidance.py b/tests/test_harness_skill_guidance.pyindex c4495de1c..cac1c67f9 100644--- a/tests/test_harness_skill_guidance.py+++ b/tests/test_harness_skill_guidance.py@@ -20,6 +20,13 @@ def _read(path: str) -> str:return (ROOT / path).read_text()+def _use_avibe_references() -> list[Path]:+ directory = ROOT / "skills/use-avibe"+ targets = re.findall(r"\]\((references/[^)]+\.md)\)", (directory / "SKILL.md").read_text())+ assert targets, "the Skill entry must route to its operational references"+ return [directory / target for target in targets]++def _embedded_cli_examples(body: str) -> list[str]:"""Every embedded `vibe task/watch` example that carries at least one flag.@@ -36,7 +43,9 @@ def _embedded_cli_examples(body: str) -> list[str]:def test_avibe_compatibility_skill_teaches_current_harness_defaults() -> None:- for path in ("skills/use-avibe/SKILL.md",):+ reference = ROOT / "skills/use-avibe/references/harness.md"+ assert reference in _use_avibe_references()+ for path in ("skills/use-avibe/references/harness.md",):body = _read(path)assert "Runs are async by default" in body@@ -79,6 +88,7 @@ def test_harness_guidance_examples_parse_against_the_real_cli() -> None:)examples = _embedded_cli_examples(prompt + "\n" + _read("skills/use-avibe-harness/SKILL.md")+ + "\n" + "\n".join(path.read_text() for path in _use_avibe_references()))assert examples, "no embedded vibe task/watch examples found — did the regex drift?"@@ -117,6 +127,7 @@ def test_avibe_skills_do_not_reintroduce_legacy_harness_guidance() -> None:for path in ("skills/use-avibe/SKILL.md","skills/background-watch-hook/SKILL.md",+ *(path.relative_to(ROOT).as_posix() for path in _use_avibe_references()),):body = _read(path)for text in disallowed:@@ -140,7 +151,7 @@ def test_use_avibe_skill_keeps_its_broad_scope_without_a_session_lifecycle_proto"context compaction","active Agent Session context",):- assert text not in body+ assert text not in body + "\n".join(path.read_text() for path in _use_avibe_references())def test_use_avibe_harness_owns_the_extracted_harness_protocol() -> None:diff --git a/tests/test_prompt_studio_catalog.py b/tests/test_prompt_studio_catalog.pyindex 782109998..8b377d37c 100644--- a/tests/test_prompt_studio_catalog.py+++ b/tests/test_prompt_studio_catalog.py@@ -1,8 +1,10 @@from __future__ import annotationsimport json+import refrom pathlib import Path+from core.managed_skills import parse_skill_file, publish_builtin_skillsfrom core.prompt_registry import (PROMPT_MODULES,RenderedPromptBlock,@@ -14,6 +16,7 @@ from core.prompt_registry import (from core.prompt_studio_catalog import (PROMPT_STUDIO_CATALOG_SCHEMA,_markdown_blocks,+ _skill_documents,export_prompt_studio_catalog,)from vibe import cli@@ -74,7 +77,8 @@ def test_studio_catalog_contains_runtime_modules_and_builtin_skills() -> None:assert catalog["schema"] == PROMPT_STUDIO_CATALOG_SCHEMAassert catalog == export_prompt_studio_catalog()- runtime, *skills = catalog["documents"]+ runtime, *documents = catalog["documents"]+ skills = [document for document in documents if "parent_id" not in document]assert runtime["id"] == "runtime-core"assert [block["id"] for block in runtime["blocks"]] == [f"runtime-{module.id}" for module in PROMPT_MODULES@@ -91,6 +95,97 @@ def test_studio_catalog_contains_runtime_modules_and_builtin_skills() -> None:}+def test_reference_documents_are_source_addressable_and_grouped_with_their_skill() -> None:+ documents = export_prompt_studio_catalog()["documents"]+ references = [document for document in documents if document.get("parent_id") == "skill-use-avibe"]+ files = sorted((ROOT / "skills/use-avibe/references").rglob("*.md"))+ assert [document["source_path"] for document in references] == [path.relative_to(ROOT).as_posix() for path in files]+ assert len(references) == 7+ start = next(index for index, document in enumerate(documents) if document["id"] == "skill-use-avibe")+ assert documents[start + 1:start + 1 + len(references)] == references+ ids = [document["id"] for document in documents]+ for document in documents:+ ids.extend(block["id"] for block in document["blocks"])+ if document.get("parent_id"):+ lines = (ROOT / document["source_path"]).read_text(encoding="utf-8").splitlines()+ for block in document["blocks"]:+ assert block["source_path"] == document["source_path"]+ assert "\n".join(lines[block["source_line"] - 1:]).startswith(block["source"])+ assert len(ids) == len(set(ids))+ assert all(re.fullmatch(r"[a-zA-Z0-9_-]{1,200}", identity) for identity in ids)+++def test_reference_edits_additions_and_deletions_do_not_rekey_other_documents(tmp_path, monkeypatch) -> None:+ monkeypatch.setattr("core.prompt_studio_catalog.builtin_skills_source", lambda: tmp_path)+ directory = tmp_path / "example"+ directory.mkdir()+ (directory / "SKILL.md").write_text("---\nname: example\ndescription: Fixture\n---\n# Entry\nRead references.\n")+ references = directory / "references"+ references.mkdir()+ nested = references / "nested"+ nested.mkdir()+ file = nested / "detail.md"+ file.write_text("# Details\n\nFirst version.\n\n```sh\n# Not a heading\n```\n")+ (references / "ignored.txt").write_text("Not Markdown")+ (directory / "scripts").mkdir()+ (directory / "scripts/example.md").write_text("Not a reference")+ initial = _skill_documents()+ assert len(initial) == 2+ assert len(initial[1]["blocks"]) == 1+ file.write_text("# Details\n\nSecond version.\n")+ (references / "earlier.md").write_text("# Details\n\nAnother file.\n")+ edited = _skill_documents()+ assert edited[0] == initial[0]+ assert edited[2]["id"] == initial[1]["id"]+ assert edited[2]["blocks"][0]["id"] == initial[1]["blocks"][0]["id"]+ assert edited[2]["revision"] != initial[1]["revision"]+ assert edited[1]["blocks"][0]["id"] != edited[2]["blocks"][0]["id"]+ file.unlink()+ assert _skill_documents() == edited[:2]+++def test_reference_export_does_not_follow_symbolic_links(tmp_path, monkeypatch) -> None:+ monkeypatch.setattr("core.prompt_studio_catalog.builtin_skills_source", lambda: tmp_path / "skills")+ directory = tmp_path / "skills/example"+ directory.mkdir(parents=True)+ (directory / "SKILL.md").write_text("---\nname: example\ndescription: Fixture\n---\n# Entry\n")+ outside = tmp_path / "private"+ outside.mkdir()+ (outside / "secret.md").write_text("Private file")+ references = directory / "references"+ references.symlink_to(outside, target_is_directory=True)+ assert len(_skill_documents()) == 1+ references.unlink()+ references.mkdir()+ (references / "directory-link").symlink_to(outside, target_is_directory=True)+ (references / "file-link.md").symlink_to(outside / "secret.md")+ assert len(_skill_documents()) == 1+++def test_use_avibe_entry_routes_to_all_bundled_references() -> None:+ directory = ROOT / "skills/use-avibe"+ entry = (directory / "SKILL.md").read_text(encoding="utf-8")+ assert len(entry.splitlines()) < 150+ targets = re.findall(r"\]\((references/[^)]+\.md)\)", entry)+ assert set(targets) == {path.relative_to(directory).as_posix() for path in (directory / "references").glob("*.md")}+ assert all((directory / target).is_file() for target in targets)+ assert (directory / "scripts/vibe_api.py").is_file()+ for rule in ("preserve every existing channel", "missing user fields are not a patch", "Do not restart", "Treat secrets as opaque"):+ assert rule in entry+++def test_published_skill_keeps_references_available_without_eagerly_loading_them(tmp_path) -> None:+ destination = tmp_path / "snapshots"+ snapshot = publish_builtin_skills(source_root=ROOT / "skills", destination_root=destination)+ directory = destination / snapshot / "use-avibe"+ skill = parse_skill_file(directory / "SKILL.md", priority=(0, 0, 0, str(directory)), include_body=True)+ assert skill is not None+ assert "references/global-config.md" in skill.body+ assert '"cloudflared_path"' not in skill.body+ for source in (ROOT / "skills/use-avibe/references").glob("*.md"):+ assert (directory / "references" / source.name).read_bytes() == source.read_bytes()++def test_skill_sections_ignore_heading_like_lines_inside_code_fences() -> None:blocks = _markdown_blocks("# Real\n\n```sh\n# shell comment\n```\n\n## Also real\n",