AetherAI3 · AetherAI3 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026
diff --git a/COMMANDS.md b/COMMANDS.md
@@ -15,12 +15,12 @@ aether                                  # no args = interactive REPL
 
 <!-- CLI-COMMANDS:START -->
 `help`, `agent`, `chat`, `resume`, `run`, `models`, `agents`, `auth`,
-`github`, `vault`, `workflow`, `memory`, `image`, `video`, `output`, `audit`,
-`receipt`, `doctor`, `mcp`, `config`
+`github`, `vault`, `workflow`, `memory`, `skills`, `capabilities`, `image`, `video`, `output`,
+`audit`, `receipt`, `doctor`, `support-bundle`, `mcp`, `config`
 <!-- CLI-COMMANDS:END -->
 
 <!-- SLASH-COMMANDS:START -->
-`help`, `models`, `model`, `agent`, `agents`, `tier`, `audit`, `effort`, `doctor`, `clear`, `exit`, `mcp`, `autonomous-execution`, `subagent-driven-execution`, `self-review`, `recon`, `plan`, `research`, `review`, `code-review`, `writing-skills`, `writing-plans`, `queue`, `steer`, `btw`, `pin`, `drop`, `snapshot`, `limit`, `audit-receipt`, `rollback`, `logs-view`, `goal`, `goals`, `memory`, `workflow`, `workflow-templates`, `workflow-template`, `vault`, `vault-context`, `vault-search`, `vault-recent`, `vault-project`, `vault-tag`, `vault-tree`, `delegate`, `tree`, `broadcast`, `gather`, `scaffold`, `port`, `test-drive`, `bench`, `purge`, `stage-diff`, `revert`, `photogen`, `frame`, `re-frame`, `videogen`, `sequence`, `animate`, `re-cut`, `output`, `storyboard`, `add`, `hud`
+`help`, `models`, `model`, `agent`, `agents`, `tier`, `audit`, `effort`, `doctor`, `clear`, `exit`, `mcp`, `skills`, `why`, `autonomous-execution`, `subagent-driven-execution`, `self-review`, `recon`, `plan`, `research`, `review`, `code-review`, `writing-skills`, `writing-plans`, `queue`, `steer`, `btw`, `pin`, `drop`, `snapshot`, `limit`, `audit-receipt`, `rollback`, `logs-view`, `goal`, `goals`, `memory`, `workflow`, `workflow-templates`, `workflow-template`, `vault`, `vault-context`, `vault-search`, `vault-recent`, `vault-project`, `vault-tag`, `vault-tree`, `delegate`, `tree`, `broadcast`, `gather`, `scaffold`, `port`, `test-drive`, `bench`, `purge`, `stage-diff`, `revert`, `photogen`, `frame`, `re-frame`, `videogen`, `sequence`, `animate`, `re-cut`, `output`, `storyboard`, `add`, `hud`
 <!-- SLASH-COMMANDS:END -->
 
 
@@ -150,16 +150,47 @@ Exports the cryptographic proof package for one audit entry. Find ids with
 aether receipt chat_8f3a...
 ```
 
-### `aether doctor [--deep]` — runtime diagnostics
-Runs an ordered set of structured checks — auth, network reachability,
-config integrity, MCP registry health, and more — and prints a pass/fail
-summary. `--deep` adds slower, bounded checks on top of the fast baseline.
-Exits `1` if any check fails, so it's safe to gate scripts on.
+### `aether doctor [--network] [--fix]` — runtime diagnostics
+Runs an ordered set of structured checks — auth, config integrity, MCP
+registry health, skill index/lock/trust, instruction conflicts, and more —
+grouped by category with a pass/fail summary. The fast default makes no
+network calls and no mutations; `--network` (alias `--deep`) adds slower,
+bounded backend probes plus a capability-manifest fetch. Exits `1` if any
+check fails, so it's safe to gate scripts on.
+
+Flags: `--category a,b` runs only those categories; `--failed` shows only
+warn/fail checks (the summary still reflects the full run); `--junit <path>`
+writes a JUnit XML report for CI. `--json` emits the stable v1 report shape
+by default — pass `--schema v2` for the richer v2 schema (severity,
+configured/reachable/verified state, repair ids).
+
+`--fix` prints a dry-run repair plan (rebuild corrupt skill stores, create a
+missing config dir, remove stale temp files); `--fix --yes` applies it with
+backup-first transactions and appends metadata-only receipts to
+`repair-receipts.jsonl` in the config directory.
 
 ```bash
 aether doctor
-aether doctor --deep
-aether doctor --json
+aether doctor --network
+aether doctor --json                 # v1 shape
+aether doctor --json --schema v2     # v2 shape
+aether doctor --category skills,mcp --failed
+aether doctor --junit doctor.xml
+aether doctor --fix --yes
+```
+
+### `aether support-bundle` — redacted diagnostic archive
+Packages a metadata-only diagnostic bundle as a single uncompressed `.tar`
+in the current directory: fast doctor report, runtime/config summaries,
+skill and instruction inventories (digests and counts, never content), and
+the last 200 redacted session event lines, plus a hash manifest. The bundle
+is reopened, secret-scanned, and hash-verified before it is finalized — on
+any failure nothing is left behind and the command exits `1`. Tokens, env
+values, file contents, and private absolute paths are never included.
+
+```bash
+aether support-bundle
+aether support-bundle --json
 ```
 
 ### `aether mcp [list|doctor|repair]` — manage and diagnose MCP servers
@@ -174,6 +205,26 @@ disconnect actions per entry.
 | `aether mcp doctor` | Same report; exits `1` if any check fails (scriptable health gate). |
 | `aether mcp repair` | Back up and reset a corrupted local MCP registry (confirms first). |
 
+### `aether skills <subcommand>` — agent skills
+Discovers built-in, user (`~/.config/aether/skills/user/`), and project
+(`.aether/skills/project/`) skills. Project skills are untrusted until you
+inspect and trust them; trust binds to the exact content digest, so any change
+requires re-trust. The REPL `/skills` command covers the read/toggle subset —
+trust decisions stay in the CLI.
+
+| Subcommand | Does |
+|---|---|
+| `aether skills list` | Index of discovered skills: id, scope, trust, enabled, automatic, token cost. `--json` prints the raw index. |
+| `aether skills show <id>` | Metadata, digest, and declared tool/permission policy (never the body). |
+| `aether skills explain <id>` | `show` plus the files that would load and the effective tool policy. |
+| `aether skills create <name> [--scope project\|user]` | Scaffold a new skill directory (default: project). |
+| `aether skills install <path> [--scope project\|user]` | Validate and copy a local skill directory into the scope root. |
+| `aether skills enable <id>` / `disable <id>` | Toggle a skill locally. |
+| `aether skills trust <id>` | Show digest + requested permissions, then record trust (`--yes` or interactive y/N; fails closed without a TTY). |
+| `aether skills untrust <id>` | Remove the local trust record. |
+| `aether skills lock` | Write `.aether/skills.lock.json` for project skills (safe to commit). |
+| `aether skills check [id\|--all] [--ci]` | Static checks: schema, lock drift, trust, dependency graph, eval fixtures. `--ci` exits `1` on failure; `--json` for structured output. |
+
 ### `aether config [show|get|set]` — local settings
 Local settings, stored at `~/.config/aether/config.json`.
 ```bash
@@ -216,6 +267,7 @@ mirrors the live registry in `src/commands/slash_registry.ts`.
 | `/doctor [deep]` | Run ordered diagnostics; `deep` adds bounded checks. |
 | `/clear` | Clear the screen. |
 | `/mcp [list|doctor|repair]` | Diagnose or confirmation-gated repair for MCP servers. |
+| `/skills [list|show <id>|enable <id>|disable <id>]` | List and manage agent skills. Trust stays in the CLI: `aether skills trust <id>`. |
 | `/exit`, `/quit` | Leave the REPL. |
 
 Typos get a nudge: `/modle` answers `did you mean /model?`. Tab completes any

diff --git a/README.md b/README.md
@@ -74,7 +74,7 @@ Six frontier models, every one with a million-token window. In the GPT-5.6 famil
 |---|---|
 | **Free** | Claude Haiku 4.5 · DeepSeek V4 Flash · one image model as a teaser |
 | **Solo** | + Claude Sonnet 5 · GPT-5.4 mini · the **Neo 5.1T** orchestrator · the full image fleet |
-| **Pro / Team** | + Claude Opus 4.8 · GPT-5.5 · DeepSeek V4 Pro · Kimi K2.6 · Gemma 4 31B · the six frontier models above · video & 3D generation · the **Kronus v2.4** and **Aether-Vision** orchestrators |
+| **Pro / Team** | + the six frontier models above — **Claude Opus 5 · GPT-5.6 Sol / Terra / Luna · Kimi K3 · Gemini 3.6 Flash** — plus the previous generation, still fully selectable (Claude Opus 4.8 · GPT-5.5 · DeepSeek V4 Pro · Kimi K2.6 · Gemma 4 31B) · video & 3D generation · the **Kronus v2.4** and **Aether-Vision** orchestrators |
 
 Media is 15 image models (Nano Banana Pro & 2, FLUX.2 Klein / Pro / Flex / Max, Recraft V3 & V4, Seedream 4.5, Riverflow V2, GPT-5 Image), 16 video models (Seedance 2.0 & 1.5 Pro, Veo 3.1 / Fast / Lite, Kling 3.0 Standard & Pro, Kling Video O1, Sora 2 Pro, Wan 2.6 & 2.7, Hailuo 2.3, HunyuanVideo 1.5, Grok Imagine), and Hunyuan3D 2.1 for text-to-3D — all drivable from the prompt line with `/photogen`, `/videogen` and `/storyboard`.
 

diff --git a/docs/releases/2026-08-skills-health-release-record.md b/docs/releases/2026-08-skills-health-release-record.md
@@ -0,0 +1,59 @@
+# Skills & Health — Release Record (Aether Agent Release 5)
+
+Status: IN PROGRESS — fields marked TBD are filled at each rollout stage.
+No secrets, customer content, or internal topology belong in this file.
+
+## Contract versions
+
+| Contract | Version |
+|---|---|
+| Skill schema (aether.skill/v1) | 1 |
+| Skill context packet | 1 |
+| Instruction context packet | 1 |
+| Capability contract | 1 |
+| Doctor report schema | 2 (v1 adapter preserved) |
+| Support bundle schema | 1 |
+| Dev-session protocol | 1 (additive fields only) |
+
+## Commits and digests
+
+- AETHER-CLOUD baseline at kickoff: `4e6b9e2b150de0dadf3b213fbd988987cd48a8b5`
+- aether-agent baseline at kickoff: `b98ef26d16daf61a32a6c0ca437172d794b2efe1`
+- PR A (cloud foundation, dark): AetherAI3/AETHER-CLOUD#1065 — merged SHA: `97eacd3e9aca4df226cae638f8f8868b8219fe88` (2026-08-15, deployed dark; required checks python/site/web green + desktop; site rerun after a runner font-fetch flake)
+- PR B (agent release): TBD
+- PR C (activation): TBD
+- Capability contract canonical sha256: `8da094234a370a28dfd6206f039425f086307aa9ca0a67bc004d3d453716ac04`
+  (verified byte-identical between Python `contract_digest()` and the TS generator)
+- npm package digest: TBD (at Stage 3)
+
+## Test counts (latest full runs)
+
+- aether-agent `npm test`: full suite green after the instruction-extraction fix (TBD exact count at PR B CI)
+- AETHER-CLOUD targeted batch: 527 passed (agent_dev, agent_capabilities, capability routes, dev-session routes, flags, web_artifacts, OpenAPI snapshot)
+- Site vitest: 2117/2118 locally (1 pre-existing Windows CRLF hash issue; linux CI green: TBD confirm on PR A)
+- Desktop quick gates: 17/17
+
+## Live proof (Stage 2 canary)
+
+TBD — record timestamps and outcomes for the §24 sequence (trust lifecycle,
+undeclared-tool block, network block, nested AGENTS.md scope, conflict
+resolution, doctor fast/network/live, safe repair, support-bundle canary scan,
+digest parity across surfaces, installed-package smoke).
+
+## Known limits
+
+- No remote skill marketplace in v1; no skill scripts or hooks.
+- Project skills require explicit digest-bound trust.
+- Live provider proof is separately authorized (`--live --provider --max-uvt`).
+- Cursor rule support covers the simple glob subset only; unsupported syntax
+  warns and the rule is not applied.
+- Hosted skill context requires a server with capability contract v1; legacy
+  servers refuse with `skill.server_unsupported` unless `--no-skills`.
+
+## Rollback path
+
+- Disable hosted skill context: unset `AETHER_AGENT_SKILLS_ENABLED` (flag trio; per-user overrides available).
+- Client falls back to local skills and the packaged capability snapshot automatically.
+- Disable automatic selection while preserving explicit invocation: per-skill `aether skills disable`, or remove the local automatic opt-ins.
+- Agent package rollback through the signed npm release channel.
+- Rollback never rewrites a user's project skills or committed lock.
diff --git a/docs/releases/SKILLS_HEALTH_CURRENT_STATE.md b/docs/releases/SKILLS_HEALTH_CURRENT_STATE.md
@@ -0,0 +1,67 @@
+# Skills & Health Release — aether-agent Current State
+
+Recorded: 2026-08-14. Baseline `origin/main` SHA: `b98ef26d16daf61a32a6c0ca437172d794b2efe1`.
+Lane branch: `feat/skills-health` (worktree `~/aether-skills-wt`).
+
+## Overlap decision
+
+Open PRs at kickoff: #62/#63/#64 (dependabot GitHub Actions bumps), #36 (docs spec loop).
+None touches skills, doctor, instructions, capability contracts, or dev sessions.
+No competing branch owns this lane. Recently merged: bidirectional CloudBrain
+(`feat/cloud-brain-bidirectional`, now in main as `b98ef26`) — this lane builds on top of it,
+not around it.
+
+## Source-of-truth map (as of baseline)
+
+| Concern | Source of truth |
+|---|---|
+| CLI commands | `src/commands/cli_registry.ts` (`CLI_COMMANDS`, validated at import) |
+| Slash commands | `src/commands/slash_registry.ts` + `handleSlash` switch in `src/commands/slash.ts`; parity tests parse the switch source (`test/slash_registry.test.ts`) and `COMMANDS.md` marker blocks (`test/command_docs_parity.test.ts`) |
+| Tool names | `src/core/brain_protocol.ts` `TOOLS` (frozen 8: read_file, write_file, run_shell, run_tests, repo_search, git_commit, web_search, web_fetch) |
+| Tool schemas + side-effect classes | `src/core/tool_registry.ts` (`TOOL_DEFINITIONS`, `ToolSideEffect = read\|write\|shell\|git\|network`, `validateToolDefinitionCoverage`) |
+| Tool execution | `src/core/tool_executor.ts` (workspace escape guard `safe()`, output caps) |
+| Permission modes | `src/types.ts` `PermissionMode = ask\|auto\|skip` + `autoApply`; gate logic `src/core/autonomy.ts` (`gateActionFor`, `decideGate`, fail-closed no-TTY) |
+| Effort tiers | `src/ui/effort.ts` `EFFORT_TIERS = LOW/MED/HIGH/MAX/ULTRA/CODEPRO` |
+| Bridge protocol | `src/core/brain_protocol.ts` `PROTOCOL_VERSION = 3`; fixture `test/fixtures/bridge_conformance.json`; docs `docs/CONTRACTS.md`, `docs/BRIDGE_PROTOCOL.md` |
+| Dev-session wire | `src/core/brain_cloud.ts` `DEV_PROTOCOL_VERSION = 1`; request shape `src/core/envelope.ts` `DevSessionWireRequest` |
+| Config root | `src/core/config.ts` `configDir()` = `$AETHER_CONFIG_DIR` ?? `~/.config/aether` (all platforms) |
+| Logs root | `~/.aether-agent/logs` (`src/core/session_log.ts`) |
+| Doctor | `src/commands/doctor.ts` (30 lines) + `src/core/diagnostics.ts` (12 hardcoded checks, `schemaVersion: 1`, `--deep`) |
+| Redaction | module-private helpers in `src/core/session_log.ts` (`redactInline`, `loggedArgs`, `loggedEvent`) |
+| Release policy | `scripts/verify-production.ts` (zero runtime deps, exact pack allowlist, size ≤ 5 MB, SHA-pinned actions) |
+
+## What does NOT exist yet (greenfield for this release)
+
+- No local skill system: no loader, no `SKILL.md`, no skills directory, no `/skills`, no `aether skills`.
+- No instruction-file reading: zero references to `AGENTS.md` / `CLAUDE.md` anywhere in src.
+- No support bundle; redaction primitives exist but are private to `session_log.ts`.
+- No capability manifest or generated contract files.
+- No check registry inside doctor — checks are an inline array in `diagnosticReport()`.
+
+## Behavioral memory vs Agent Skills
+
+The existing "skills" are cloud-hosted QOPC procedural memory rows
+(`src/core/cloud_memory.ts`, memory tier `procedural` in `src/core/memory.ts`,
+wire event `{type:"skill"}` in `brain_protocol.ts`). They are learned behavioral
+descriptions with no version, no digest, no tool policy, no trust state, and no
+invocation path. This release does NOT rename or remove them. They remain
+"behavioral memory". "Agent Skills" in this release means the new versioned,
+digest-bound, permission-declared, invokable packages defined by
+`aether.skill/v1`. UI copy must keep the two distinct.
+
+## Constraints inherited from the repo
+
+- Zero runtime dependencies (verify-production hard-fails otherwise) — so strict JSON metadata, no YAML parser.
+- npm pack allowlist is exact: new built-in skill resources must ship under `dist/src/**` (compiled-adjacent copy step or embedded strings) — `files` changes must update `scripts/verify-production.ts` expectations deliberately.
+- Tests are TS compiled to `dist/test/**`; fixtures referenced relative to dist need `../../` hops.
+- tsconfig is maximally strict (`noPropertyAccessFromIndexSignature` etc.).
+- Adding a command touches 4 places: registry, dispatch switch, `COMMANDS.md` marker block, tests.
+- `capabilities: TOOLS` currently sent unfiltered on dev-session create — insertion point for skill-scoped capability sets; shape changes need additive versioned fields, keep `DEV_PROTOCOL_VERSION = 1` negotiation intact.
+- Known gap to fix per spec §7.3: `web_search`/`web_fetch` have `sideEffect: "network"` which maps to no gate (`gateActionFor` returns null) — network currently bypasses the mutation gate.
+- CI: `.github/workflows/ci.yml` runs on GitHub-hosted `ubuntu-latest` + `windows-latest` in this repo (matrix build-and-test + supply-chain job). CodeQL weekly. Release workflow publishes with provenance. Any workflow edit must keep: explicit permissions, 40-hex SHA pins, `npm ci --ignore-scripts`, runs-on/timeout parity — enforced by `verify-production` and `test/production_hardening.test.ts`.
+
+## Dependency order for this lane
+
+1. PR A (AETHER-CLOUD): capability contract, hosted skill/instruction context validation, ack frames, feature flag — deployed dark.
+2. PR B (aether-agent, this worktree): skill engine, instructions, doctor v2, safe repair, support bundle, capability fallback pinned to PR A's merged SHA.
+3. PR C: activation + release proof.
diff --git a/docs/skills/AUTHORING.md b/docs/skills/AUTHORING.md
@@ -0,0 +1,69 @@
+# Authoring Agent Skills
+
+An Agent Skill is a versioned, digest-bound instruction package. It never
+grants authority: the effective tool set is always the intersection of the
+operator's session policy, the skill's declarations, and the workspace
+boundary. A missing declaration fails closed.
+
+## Layout
+
+```
+.aether/skills/project/<name>/     project skill (untrusted until trusted)
+  skill.json                       aether.skill/v1 manifest (strict JSON)
+  SKILL.md                         instructions (loaded only on invocation)
+  references/                      optional resources (must be declared)
+  evals/cases.json                 offline eval cases (recommended)
+```
+
+User skills live under `<configDir>/skills/user/<name>/` (default
+`~/.config/aether/skills/user`). Built-ins ship inside the npm package under
+the reserved `aether/*` namespace.
+
+## Manifest rules (aether.skill/v1)
+
+- `schema_version` must be `1`; unknown keys are hard errors.
+- `id` is `<scope>/<kebab-name>`; scope must match where the skill lives.
+- `version` is strict semver `MAJOR.MINOR.PATCH`.
+- `tools.required ⊆ tools.allowed`; `tools.denied ∩ tools.allowed = ∅`;
+  only canonical tool names (read_file, write_file, run_shell, run_tests,
+  repo_search, git_commit, web_search, web_fetch).
+- Permissions come from the closed vocabulary (`workspace.read`,
+  `shell.test`, `network.general`, …). `workspace.outside`, `secrets.read`,
+  and `billing.spend` cannot be declared by any skill.
+- All resource paths are relative, no `..`, no absolute paths, no URLs.
+- Resources are loaded ONLY if listed in `context.resources`.
+
+## Digest and trust
+
+One canonical SHA-256 covers the normalized manifest, `SKILL.md`, and every
+declared resource/eval file. Trust binds to that digest: change one byte and
+the skill returns to `changed · review required`. `aether skills trust <id>`
+records trust locally (never in the repo); `aether skills lock` writes the
+committed-safe `.aether/skills.lock.json` (digests only, no trust).
+
+## Lifecycle commands
+
+```
+aether skills create <name> --scope project|user
+aether skills check <id> | --all [--ci]
+aether skills eval  <id> | --all [--json] [--junit <path>]
+aether skills trust <id>            # inspect digest + permissions, then confirm
+aether agent --skill <id> "task"    # explicit invocation
+```
+
+Automatic selection requires `triggers.automatic: true` AND (for user/project
+skills) an explicit local opt-in — and project skills must be trusted. At most
+3 automatic skills load per turn; skill bodies are lazy-loaded only after
+selection.
+
+## Evals
+
+`evals/cases.json` is a JSON array of cases:
+
+```json
+{ "id": "denies-undeclared-write", "input": "…",
+  "expected": { "selected_skill": "project/x", "allowed_tools": ["read_file"],
+                 "forbidden_tools": ["write_file"], "max_uvt": 0 } }
+```
+
+Offline evals are zero-spend by construction — `max_uvt` must be 0.