@aopslabs/aops 0.3.30 → 0.3.32

package/aops-assets-release/skills/aops-cli-sugar-authoring/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: aops-cli-sugar-authoring
+description: "Use when an AI agent needs to author or extend a sugar CLI command (eops-cli or aops-cli) over a hosted domain operation. Thin discipline guide: identifies the right command surface, points to canonical authoring sources, and keeps every new sugar wired to `agent schema` discovery so callers stop guessing payload fields."
+metadata:
+  short-description: "AOPS/EOPS CLI sugar-authoring thin discipline guide"
+  tags:
+    - cli
+    - authoring
+    - sugar
+    - host-plugin
+    - agent-schema
+---
+
+# AOPS/EOPS CLI Sugar Authoring
+
+This skill is a thin authoring playbook for adding or extending sugar CLI
+commands on `aops-cli` or `eops-cli` over an already-registered hosted domain
+operation. It does **not** cover authoring new operations inside a domain kit
+or host plugin — that path is the kit/host-plugin authoring flow.
+
+When this skill conflicts with the architecture doc or `--help`, those win.
+
+## When To Use This Skill
+
+1. Adding a new `aops-cli <domain> <subcommand>` or `eops-cli <domain> <subcommand>` over a hosted operation that already exists in the kit/host-plugin manifest.
+2. Extending or splitting an existing sugar (new option, new alias, new validation).
+3. Wiring a composite sugar that orchestrates multiple hosted operations under one CLI entry.
+
+Out of scope: adding a new operation to a domain kit, exposing it through the host plugin, or changing the federated catalog. Use the kit/host-plugin authoring flow for those — see slug:aops `tooling-cli-host-plugin-system`, the "Domain Kit Katmanı" section (search: domain kit, operation contract) and the "Domain Capability Manifest (DCM)" section (search: DCM, capability manifest, discovery metadata).
+
+## Canonical Sources
+
+When this skill is silent, ambiguous, or out of date, defer to these:
+
+1. slug:aops `tooling-cli-host-plugin-system`, the "Agent Gateway" section (search: agent gateway, tool invoke envelope, public discovery surface) and the "CLI Sistemi" section (search: CLI sistemi, CLI dispatch, registration) — canonical mechanics for invoke routing, public discovery surface, and CLI dispatch.
+2. slug:aops `tooling-cli-host-plugin-system`, the "Tool Input JSON Schema Discovery" section (search: tool input json schema, agent schema, inputJsonSchema) — the `agent schema` contract every new sugar must integrate with.
+3. `aops-cli <command> --help` / `eops-cli <command> --help` for live flag truth.
+4. Existing sugar source files (read these as templates):
+   - aops-cli, commander-based: `apps/aops/apps/aops-cli/src/commands/agent.ts`, `apps/aops/apps/aops-cli/src/commands/docman.ts`
+   - eops-cli, manual argv + topic registry: `apps/eops/apps/eops-cli/src/commands/inventory.ts` (help registry) and `apps/eops/apps/eops-cli/src/commands/inventory-bom.ts` (builder dispatch)
+
+## Pre-Authoring Discovery
+
+Before writing any new sugar:
+
+```bash
+# Confirm the target operation is registered
+aops-cli agent tools --domain <id> --json | jq '.tools[] | select(.toolId | test("<op-substr>"))'
+# OR
+eops-cli agent tools --domain <id> | grep <op-substr>
+
+# Pull the live input contract — this is the payload-shape contract you wrap
+aops-cli agent schema --tool <domain>.<operation>
+eops-cli agent schema --tool <domain>.<operation>
+
+# Read the kit's host-route projection to see the HTTP shape (params, method)
+# broad search across the project's guides (local mirror, no id needed):
+aops-cli doc scope search --project-slug aops --q "host-projection" --local --json
+# exact search within a known guide version:
+aops-cli doc search --document-version-id <docver-id> --q "host-projection" --local --json
+# section tree of a known guide version (hosted-only — no local fallback):
+aops-cli doc outline get --document-version-id <docver-id> --json
+```
+
+There is no `aops-cli docman … --slug` command — use the ladder; reference sections by document title + section name + keywords, not bare numbers.
+
+Decisions you should resolve before writing code:
+
+1. Is this a thin wrapper over a single operation or a composite over multiple?
+2. Does it need a request body (`--data`/`--input`/`--patch`) or only positional/route args?
+3. Is it a hosted write (`--apply`/`--confirm` guards) or read-only?
+4. Which CLI is the home (aops-cli or eops-cli)? Operator surfaces follow the app that owns the domain; if both apps consume the operation, prefer the canonical operator plane (aops-cli).
+
+## Authoring Pattern — aops-cli (commander)
+
+aops-cli uses `commander`. Help is auto-generated from `.command/.description/.option` calls.
+
+1. Open the domain commander file: `apps/aops/apps/aops-cli/src/commands/<domain>.ts` (e.g. `agent.ts`, `docman.ts`, `projectman.ts`).
+2. Inside the `make<Domain>Command()` factory append a new subcommand:
+
+   ```ts
+   applyCommonOptions(
+     cmd
+       .command('<sub>')
+       .description('<one-line description of what it does>')
+       .option('--<flag> <value>', '<help text>')
+       .action(async (options: <SubOptions>) => {
+         await run<Sub>(options)
+       }),
+     { withProject: true /* or false for read-only/global */ }
+   )
+   ```
+
+3. Implement `run<Sub>(options)` next to the other run functions. Reuse:
+   - `requireApiState(options)` for auth/base-url plumbing
+   - `buildAgentContextHeaders(options)` for `x-tenant-id`/`x-scope-id`/etc.
+   - `invokeHostedToolWithApiState(apiState, { toolId, input, ... })` for hosted invokes
+   - `apiState.client.fetchJson(...)` for direct discovery/read endpoints
+   - `unwrapHostedToolResult(payload)` to surface the data result
+   - `parseJsonInput(options.input, 'input')` for JSON payloads / `@file.json`
+4. Add an example to `cmd.addHelpText('after', ...)` showing the canonical workflow. Always include the `agent schema --tool <id>` pre-step when the command takes `--data`/`--input`/`--patch`.
+
+## Authoring Pattern — eops-cli (manual argv + topic registry)
+
+eops-cli renders `--help` from a declarative topic registry and dispatches via builder functions.
+
+1. Open the topic registry file: `apps/eops/apps/eops-cli/src/commands/<domain>.ts` (e.g. `inventory.ts`).
+2. Append a topic entry:
+
+   ```ts
+   {
+     route: ['<domain>', '<entity>', '<sub>'],
+     summary: '<one-line summary>',
+     usage: [
+       'eops-cli <domain> <entity> <sub> --<flag> <value> [--apply --confirm]',
+     ],
+     options: [
+       '--data / --payload / --file: JSON object forwarded as <entity> data',
+       '--apply --confirm: required together for hosted writes',
+       '--idempotency-key: optional hosted write idempotency key when --apply is used',
+     ],
+     notes: [
+       // CRITICAL: always include this notes line for write-shaped sugars.
+       'Run `eops-cli agent schema --tool <domain>.<operation>` to fetch the live input contract before authoring --data payloads.',
+       // Plus any non-obvious field-ownership / lifecycle notes.
+     ],
+     examples: [
+       'eops-cli <domain> <entity> <sub> --data @./payload.json',
+       'eops-cli <domain> <entity> <sub> --data @./payload.json --apply --confirm',
+     ],
+   },
+   ```
+
+3. Add a builder function `build<Sub>Command(section, action, parsed)` in the builder file (e.g. `inventory-bom.ts`). Return `{ action, operationId, input, write? }`.
+4. Wire the builder into the dispatch chain so the right action returns from `build<Domain>Command(section, action, parsed)`.
+5. Verify with `pnpm --filter @eops/eops-cli run build && eops-cli <domain> <entity> <sub> --help`.
+
+## Schema Discovery Integration (Required)
+
+Every new sugar that accepts `--data` / `--input` / `--patch` must point operators to `agent schema --tool <toolId>` in its help/notes. Reasons:
+
+1. `agent schema` is the canonical pre-authoring contract; without the pointer, operators and AI agents will guess field names and hit `Invalid input` from `z.union`-shaped validators.
+2. Consistency across the kit family — every operator skill already cross-references this step.
+3. When the kit later changes a field, `agent schema` reflects the change immediately; inline help-text field lists drift.
+
+Read-only sugars (list/get/search/view) do not require the pointer.
+
+## Always Rules
+
+1. Reuse the canonical helpers — never reinvent `--apply`/`--confirm`/`--idempotency-key` parsing.
+2. Hosted writes go through `invokeHostedToolWithApiState` (aops-cli) or the existing hosted dispatch in eops-cli — never bypass the gateway.
+3. Help text for write sugars MUST include the `agent schema --tool <toolId>` line.
+4. After authoring, run `--help` and `agent schema --tool <id>` against the new command path to verify discoverability before declaring done.
+5. Run a `--preview` invoke (where supported) and a real `--apply --confirm` invoke for at least one happy-path payload.
+
+## Top Anti-Patterns
+
+1. Authoring a sugar that bypasses the agent gateway and talks to the domain DB directly.
+2. Hardcoding payload field names in help text without referencing `agent schema`; the help drifts as the kit evolves.
+3. Adding a write sugar without `--apply`/`--confirm` guards.
+4. Copy-pasting argv parsing instead of importing the shared option helpers.
+5. Creating a sugar where `agent invoke --tool <id>` would suffice — sugar is justified by composite behavior, better naming, or operator ergonomics, not by personal preference.
+6. Forgetting to wire the new sugar into the dispatch chain (eops-cli) or the `make<Domain>Command()` factory (aops-cli).
+
+## Discovery Shortcuts
+
+```bash
+# broad search across the project's guides (local mirror, no id needed):
+aops-cli doc scope search --project-slug aops --q "agent gateway" --local --json
+aops-cli doc scope search --project-slug aops --q "agent schema" --local --json
+# exact search within a known guide version:
+aops-cli doc search --document-version-id <docver-id> --q "agent gateway" --local --json
+# section tree of a known guide version (hosted-only — no local fallback):
+aops-cli doc outline get --document-version-id <docver-id> --json
+aops-cli agent tools --domain <id> --json
+aops-cli agent schema --tool <domain>.<operation>
+```
+
+There is no `aops-cli docman … --slug` command — use the ladder; reference sections by document title + section name + keywords, not bare numbers.
+
+## Sister Skills
+
+- `aops-cli-core` — help-first discovery, guard flag conventions, `agent invoke` fallback.
+- `aops-cli-{agentspace,discuss,chat,docman,fileman,projectman,tasker}` — operator playbooks for each domain; consult before designing sugar UX.
+- `eops-cli-bom-authoring`, `eops-cli-sourcing-order-workbook` — concrete eops-cli sugar examples covering both read and write surfaces.
+- `aops` / `eops` — router indexes.
+
+If `--help` and this skill disagree, `--help` wins. If the architecture doc and this skill disagree, the architecture doc wins.

package/aops-assets-release/skills/aops-cli-tasker/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: aops-cli-tasker
+version: 12
+description: "Use when an AI agent needs the AOPS CLI Tasker + Runner operator playbook: choose Tasker vs Projectman, use the minimal board/task/WorkGroup sugar, inspect Runner status/events/artifacts, perform guarded stop/resume/reconcile, or discover the complete hosted Tasker catalog. Thin guide; live --help and the canonical Tasker + Runner User Guide are authoritative."
+metadata:
+  supersedes: "v11"
+  short-description: "AOPS Tasker + Runner thin operator discipline"
+  tags:
+    - cli
+    - tasker
+    - runner
+    - projectman-boundary
+    - human-first-execution
+    - guarded-control
+---
+
+# AOPS CLI Tasker + Runner
+
+Use this skill for the minimal AOPS operator sugar over the hosted Tasker
+integrated profile. It routes work; it does not copy the full hosted capability
+catalog or create a second executor.
+
+## Ownership boundary
+
+- Plan and review in Projectman: `aops pm ...`.
+- Track human-first execution in Tasker: `aops tasker ...`.
+- Read or control run state through Runner: `aops runner ...`.
+- Store durable resume and decisions in Agentspace: `aops mem ...`.
+
+A Tasker WorkGroup is an execution batch, not a Projectman sprint. Keep only a
+weak planning-origin reference when execution needs to point back to Projectman.
+
+## Start with live help
+
+```bash
+aops tasker --help
+aops tasker board --help
+aops tasker task --help
+aops tasker work-group --help
+aops runner --help
+```
+
+The installed `--help` output is authoritative for flags and command shape.
+
+## Common workflows
+
+Read Tasker state:
+
+```bash
+aops tasker board list --project-slug <slug> --json
+aops tasker task list --scope-id <scope-id> --summary --json
+aops tasker work-group list --scope-id <scope-id> --summary --json
+```
+
+Preview a task write, then apply the same intent:
+
+```bash
+aops tasker task create --scope-id <scope-id> --column <column-id> --title "<task>" --preview --json
+aops tasker task create --scope-id <scope-id> --column <column-id> --title "<task>" --apply --json
+```
+
+Read and control Runner state:
+
+```bash
+aops runner status --run-id <run-id> --include-events --summary --json
+aops runner event list --run-id <run-id> --limit 20 --summary --json
+aops runner artifact list --run-id <run-id> --summary --json
+aops runner stop --run-id <run-id> --idempotency-key <key> --preview --json
+```
+
+Stop, resume, and reconcile require `--preview` or `--apply`. Event recording
+stays executor-owned and is intentionally not operator sugar.
+
+## Complete capability discovery
+
+Sugar is intentionally bounded. For everything else, discover the running
+server instead of guessing or copying tool ids:
+
+```bash
+aops agent tools --domain tasker --summary --json
+aops agent schema --tool <tasker-tool-id> --summary --json
+```
+
+Use a sugar command's `--input '@request.json'` escape hatch for a complete
+hosted-tool input, or `aops agent invoke` when no sugar command fits.
+
+## Anti-patterns
+
+- Do not use Tasker as a second sprint or review system.
+- Do not treat WorkGroups as Projectman sprints.
+- Do not hand-edit hosted rows or `.aops` mirrors.
+- Do not infer completed work from an accepted Runner control request; read
+  status and events again.
+- Do not run a second worker, scheduler, DCM, or migration engine from this
+  skill.
+
+## Canonical sources
+
+1. Installed `aops tasker --help` and `aops runner --help`.
+2. Docman: `Tasker + Runner User Guide`, current v1
+   `53552bdc-82bb-4228-88fe-5ff0a41fdd25`.
+3. `domains/tasker/USER_GUIDE.md` as the reviewable materialization of that
+   canonical guide.
+4. Docman: `Tasker Architecture` for developer-only package, database,
+   profile, and Runner ownership contracts.
+
+If these disagree, use live help for command syntax, the User Guide for operator
+semantics, and Tasker Architecture for implementation boundaries.

package/aops-assets-release/skills/aops-cli-tooling-agent/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: aops-cli-tooling-agent
+version: 41
+description: "Compatibility index for AOPS CLI modular operator skills. Routes agents to aops-cli-core, aops-cli-discuss, aops-cli-chat, aops-cli-projectman, aops-cli-docman, aops-cli-agentspace, aops-cli-fileman, aops-cli-tasker, aops-cli-view, plus help-first and hosted mirror rules. Kept for old prompts/runtimes."
+metadata:
+  supersedes: "v40"
+  short-description: "AOPS CLI modular skill index"
+  tags:
+    - cli
+    - tooling
+    - operators
+    - index
+    - deprecated-monolith
+    - discovery
+---
+
+# AOPS CLI Tooling Agent — Modular Skill Index
+
+This skill is a **compatibility pointer**. The old monolithic `aops-cli-tooling-agent` content is split into smaller family-focused skills. Do not expand this file back into a monolith.
+
+## This skill covers
+
+1. Routing to the right AOPS CLI family skill.
+2. Help-first fallback when a family skill is unavailable in the runtime.
+3. Local cache and hosted server guard reminders.
+
+## Family skill index
+
+| Need | Skill | Canonical user guide |
+|------|-------|----------------------|
+| CLI core, guard flags, sync, hosted mirror, raw invoke | **`aops-cli-core`** | `.aops/docman/aops-guides/aops-cli-user-guide.md` (Help-first model, Guard flag konvansiyonu, Local cache and hosted server sections) |
+| discuss / decision / consensus (standalone topics, conclude outputs) | **`aops-cli-discuss`** | `.aops/docman/domain-guides/agentspace-user-guide.md` (Coordination semantics, Anti-patterns appendix sections) |
+| chat / coordination / wake (hosted rooms, DMs, listen/catchup) | **`aops-cli-chat`** | `.aops/docman/domain-guides/agentspace-user-guide.md` (Coordination semantics) |
+| review-request/result, re-review, issues, operator-approved closeout | **`aops-cli-projectman`** | `domains/projectman/USER_GUIDE.md` |
+| Projectman board/sprint/task/issue/feedback (board-lifecycle folded) | **`aops-cli-projectman`** | `domains/projectman/USER_GUIDE.md` (Projectman model, Common workflow scenarios, Cross-session handoff sections) |
+| Docman CRUD-first authoring, search, answer, publish | **`aops-cli-docman`** | `domains/docman/USER_GUIDE.md` |
+| Agentspace memory/project/prompt/resource/artifact/skill/agent-profile | **`aops-cli-agentspace`** | `.aops/docman/domain-guides/agentspace-user-guide.md` |
+| File snapshot/copy/backup/diff/restore | **`aops-cli-fileman`** | `domains/fileman/USER_GUIDE.md` |
+| Tasker / Runner workflows / tracked execution | **`aops-cli-tasker`** | `domains/tasker/USER_GUIDE.md` |
+| Read-only local-cache cockpit views | **`aops-cli-view`** | `.aops/docman/aops-guides/aops-cli-user-guide.md` (view subsection) |
+| Deprecated board-lifecycle pointer | `aops-cli-board-lifecycle` (folded into projectman) | — |
+
+## Canonical source split
+
+1. CLI command shape: `aops-cli <family> --help`.
+2. Domain semantics: the relevant hosted Docman mirror when migrated, otherwise the domain `USER_GUIDE.md` and `architecture.md`.
+3. Operator playbook + workflow patterns: hosted `aops-cli-<family>` skills.
+4. Section-focused reading: use the doc discovery ladder in the **Deep reading** section below (`aops-cli doc scope search` / `doc search` / `doc outline get`).
+
+## Compatibility fallback
+
+When a family skill is missing in the active runtime, use the help-first sequence:
+
+```bash
+aops-cli --help
+aops-cli <family> --help
+aops-cli <family> <subcommand> --help
+```
+
+Then read the matching domain guide:
+
+1. `domains/projectman/USER_GUIDE.md`
+2. `.aops/docman/domain-guides/agentspace-user-guide.md`
+3. `domains/docman/USER_GUIDE.md`
+4. `domains/fileman/USER_GUIDE.md`
+5. `domains/tasker/USER_GUIDE.md`
+6. `.aops/docman/aops-guides/aops-cli-user-guide.md`
+
+## Hosted mirror rule
+
+`.aops/hosted/**` is read-only mirror context. Hosted skill/prompt truth is changed through `aops-cli skill ...` and `aops-cli prompt ...`, then refreshed locally:
+
+```bash
+aops-cli sync pull --apply --hosted-project-slug aops --json
+```
+
+Docman guide mirrors under `.aops/docman/**` are separate. Refresh them with `aops-cli doc mirror pull --project-slug aops --group-uid <group-uid> --out-dir ./.aops/docman --apply --json`; `sync pull` does not refresh guide mirrors. In non-interactive automation, `--yes` can be added to supported commands as fail-fast mode, but it is not proof that an abort was fixed.
+
+## Guard reminder
+
+| Flag | Effect |
+|------|--------|
+| `--apply` | execute a guarded write (mostly mandatory for write commands) |
+| `--apply --confirm` | execute a destructive operation (delete/overwrite) |
+| `--json` | scriptable structured output |
+| `--idempotency-key <id>` | retry-safe writes |
+| `--preview` | validate without side effects |
+
+When in doubt: `--help` is canonical.
+
+## Deep reading
+
+For section-focused reading instead of full-file linear reads:
+
+```bash
+# broad search across the project's guides (local mirror, no id needed):
+aops-cli doc scope search --project-slug aops --q "<keyword>" --local --json
+# exact search within a known guide version:
+aops-cli doc search --document-version-id <docver-id> --q "<keyword>" --local --json
+# section tree of a known guide version (hosted-only — no local fallback):
+aops-cli doc outline get --document-version-id <docver-id> --json
+```
+
+There is no `aops-cli docman … --slug` command — use the ladder; reference sections by document title + section name + keywords, not bare numbers.
+
+## Deprecation note
+
+`aops-cli-tooling-agent` is **not hard-sunset**. It remains a stable index for old prompts, AGENTS references, and runtimes that have not switched to family-specific skills. New task prompts should prefer the smallest matching `aops-cli-<family>` skill.
+
+## Override priority
+
+If `--help` and this skill disagree, `--help` wins (canonical command surface). If the user guide and this skill disagree, the user guide wins.

package/aops-assets-release/skills/aops-cli-view/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: aops-cli-view
+version: 11
+description: "Use when an AI agent needs AOPS CLI presentation/cockpit operator playbook: discovery (read-only local-cache markdown/JSON views + hosted project inventory), selector contract, filter matrix, output controls, and view ownership boundary. Thin discipline guide; canonical mechanics live in .aops/docman/aops-guides/aops-cli-user-guide.md (AOPS markdown view sugar subsection) and command --help."
+metadata:
+  supersedes: "v10"
+  short-description: "AOPS CLI local-cache view / cockpit / presentation guide"
+  tags:
+    - cli
+    - view
+    - cockpit
+    - presentation
+    - local-cache
+    - hosted
+    - read-only
+    - markdown
+    - json
+---
+
+# AOPS CLI View
+
+`aops-cli view ...` is a **read-only presentation cockpit**. Most commands are local-cache and read local `.aops/**/*.md` files. Explicit hosted commands (`hosted-projects`, `hosted-inventory`) call hosted list APIs for inspection only. View **never** syncs, refreshes mirrors, writes cache/index files, or runs domain mutations. Default output is agent/TUI compatible markdown; `--json` returns the same read-model as a stable envelope.
+
+This skill is intentionally not a domain skill: presentation is a CLI-internal cockpit concern. **Canonical view content lives in `.aops/docman/aops-guides/aops-cli-user-guide.md`** (AOPS markdown view sugar subsection); skill text is workflow + filter/selector reference.
+
+## When to use this skill
+
+1. Local-cache dashboards (project cockpit, board, sprint, task, issue, feedback, memory, resume, discussions)
+2. Hosted project inventory inspection (`hosted-projects`, `hosted-inventory`)
+3. Skill/prompt/doc mirror views from `.aops/hosted/**`/`.aops/docman/**`
+4. Focused context pack via `digest` (sprint/task/board, depth shallow|deep)
+5. Filter and selector contract for read-only views
+
+## Use another skill for
+
+1. CLI guard flags, sync, hosted mirror mechanics: `aops-cli-core`.
+2. Planning mutations (board/sprint/task/issue/feedback create/update): `aops-cli-projectman`.
+3. Memory/agent-profile mutations: `aops-cli-agentspace`; discuss decision/consensus topics: `aops-cli-discuss`; chat coordination/wake: `aops-cli-chat`.
+4. Document graph CRUD/search/publish: `aops-cli-docman`.
+5. File snapshot/copy/backup: `aops-cli-fileman`.
+6. Tasker / runner orchestration: `aops-cli-tasker`.
+
+## Canonical sources (authoritative)
+
+When this skill is silent, ambiguous, or out of date, **defer to these**:
+
+1. `.aops/docman/aops-guides/aops-cli-user-guide.md` — canonical CLI operator guide (includes the "AOPS markdown view sugar" section under "`.aops` local cache and sync").
+2. `aops-cli view --help` and nested family help (per subcommand) — flag-level detail.
+3. Section-focused reading on the CLI user guide via the doc discovery ladder:
+   ```bash
+   # broad search across the project's guides (local mirror, no id needed):
+   aops-cli doc scope search --project-slug aops --q "view sugar" --local --json
+   # exact search within a known guide version:
+   aops-cli doc search --document-version-id <docver-id> --q "view sugar" --local --json
+   # section tree of a known guide version (hosted-only — no local fallback):
+   aops-cli doc outline get --document-version-id <docver-id> --json
+   ```
+   There is no `aops-cli docman … --slug` command — use the ladder; reference sections by document title + section name + keywords, not bare numbers.
+4. Local-cache views read `.aops/**/*.md`; hosted views read hosted list APIs. **Canonical truth still lives in the originating domain** (Projectman, Agentspace, Docman, hosted server).
+
+## Discovery: which view for what
+
+| Need | Command |
+|------|---------|
+| Project cockpit | `aops-cli view dashboard` |
+| Repo-bound projects | `aops-cli view projects` |
+| Hosted Agentspace project list | `aops-cli view hosted-projects` |
+| Per-project hosted inventory (docs/skills/prompts/resources) | `aops-cli view hosted-inventory --hosted-project <slug>` |
+| Local-cache PM list views | `aops-cli view boards/tasks/sprints/issues/feedback` |
+| Focused window detail | `aops-cli view sprint\|task\|board <selector>` |
+| Agentspace context | `aops-cli view memory/resume/experience/discussions` |
+| Hosted skill/prompt mirror | `aops-cli view skills/prompts` |
+| Docman mirror | `aops-cli view docs/doc/doc-page` |
+| Focused context pack (handoff) | `aops-cli view digest --sprint\|--task\|--board <selector> --depth shallow\|deep` |
+
+## Selector contract (essential)
+
+1. Local-cache selectors accept full UUID, 8+ char prefix, slug, or exact title.
+2. Hosted project selectors accept hosted project id, scope id, slug, name, or 8+ char prefix via `--hosted-project`.
+3. Slug match is case-insensitive; exact title/name match is whitespace-trimmed.
+4. Ambiguous selectors raise an error listing candidates so the operator can disambiguate.
+
+## Filter matrix (essential)
+
+| Komut | Filter flag'leri | Anlam |
+|-------|------------------|-------|
+| `view memory`, `view resume` | `--durability`, `--kind`, `--subject`, `--id` | durability=short\|durable\|sticky; kind=kickoff\|resume\|closeout\|note\|rule\|...; subject=project\|board\|sprint\|task\|ktask\|utask\|issue\|feedback; id=full UUID veya 8+ char prefix |
+| `view tasks` | `--board`, `--status` | board=slug/name/id; status=column adı veya slug |
+| `view issues`, `view feedback` | `--status`, `--severity`, `--board`, `--sprint`, `--task` | status=frontmatter; severity=low\|medium\|high\|critical |
+| `view sprints` | `--board`, `--status` | board=slug/name; status=todo\|doing\|completed\|paused |
+| `view discussions` | `--status`, `--agent` | status=active\|concluding\|concluded\|abandoned; agent=participants |
+| `view experience` | `--type`, `--area` | type=technique\|tool\|script\|problem-solution\|idea; area=tag |
+| `view hosted-inventory` | `--hosted-project`, `--scope-resolution` | hostedProject=id/slug/name/prefix; scopeResolution=explicit\|cascade |
+
+Filters AND together. Empty result emits `No matching records.` fallback.
+
+## Output controls
+
+| Flag | Effect |
+|------|--------|
+| `--style agent\|compact\|wide` | layout density |
+| `--json` | scriptable envelope (`surface: "local-cache-view"` or `"hosted-view"`) |
+| `--max-items <n>` | cap returned/rendered records |
+| `--max-bytes <n>` | hard-capped at 32768 |
+| `--link-mode none\|relative\|absolute` | path link rendering; default is `none` |
+
+Local-cache JSON envelope footer: `local-state` (synced/dirty/conflict/local/deleted), not raw `syncState`. Hosted JSON envelope: `surface: "hosted-view"`.
+
+Hosted commands also accept common auth flags: `--api-base-url`, `--access-token`, `--refresh-token`, `--timeout-ms`, `--tenant-id`, `--locale`, `--fallback-locale`, `--scope-id`, `--scope-resolution`. Local-cache command help may display these shared flags, but they are only used by explicit hosted view commands.
+
+## Common workflows
+
+### Workflow 1: Daily cockpit
+
+```bash
+aops-cli view dashboard --style agent
+aops-cli view boards
+aops-cli view tasks --board <slug> --status Doing
+aops-cli view issues --status open --severity high
+aops-cli view feedback --status open
+```
+
+### Workflow 2: Focused subject inspection
+
+```bash
+aops-cli view sprint <selector> --max-items 20
+aops-cli view task <selector>
+aops-cli view memory --subject sprint --id <sprint-id>
+aops-cli view resume --subject project
+```
+
+### Workflow 3: Handoff context pack
+
+```bash
+aops-cli view digest --sprint <sprint-id> --depth shallow
+aops-cli view digest --task <task-id> --depth deep --max-bytes 32768
+aops-cli view digest --board <board-slug> --depth deep
+```
+
+### Workflow 4: Hosted inventory inspection (read-only)
+
+```bash
+aops-cli view hosted-projects --style compact
+aops-cli view hosted-inventory --hosted-project <slug> --scope-resolution explicit
+```
+
+## Always rules (pointers; do not duplicate the rule body here)
+
+1. View is read-only by contract — never mutates, syncs, or refreshes mirrors.
+2. Local-cache view commands read only `.aops/**/*.md`; hosted view commands call only hosted read/list APIs.
+3. View does NOT refresh `.aops/hosted/**` or `.aops/docman/**` mirrors; use `aops-cli sync pull` for hosted prompt/skill mirrors and `aops-cli doc mirror pull` for Docman guide mirrors.
+4. Use selectors before guessing UUIDs; if a selector is ambiguous, run a list view first to disambiguate.
+5. Filter flags AND together; empty result emits `No matching records.` fallback (intentional, not an error).
+6. Use focused `view digest` over generic `view dashboard` when handing off context to another agent — digest scopes per subject and respects `--depth`.
+
+## Top anti-patterns
+
+Most common failure modes:
+
+1. **Using `view` as a mutation surface**. View is read-only by contract.
+2. **Treating `view dashboard` JSON as canonical state**. It is a composed read-model; canonical state remains per-domain.
+3. **Treating `view hosted-inventory` as sync/bootstrap**. It only reads; hosted prompt/skill mirror update is `sync pull`, while Docman guide mirror update is `doc mirror pull`.
+4. **Bypassing selector errors by guessing UUIDs**. Run a list view first when ambiguous.
+5. **Editing derived view files** (`.aops/projectman/views/index.md`, etc) — they are regenerated after every mutation.
+6. **Loading `view dashboard` for handoff** instead of focused `view digest --depth shallow|deep`.
+
+## V2 deferred surfaces
+
+Documented for awareness; not yet shipped:
+
+1. `view relations <selector>` — cross-domain RelationResolver.
+2. `view skill|prompt|experience <selector>` detail inspect.
+3. `aops-cli ls`, `aops-cli show` aliases.
+4. `--out <path>` artifact writer (stdout remains default).
+5. Hosted relation graph deeper edge resolver.
+6. Cache/index when performance demands.
+
+## Deep reading
+
+For section-focused reading instead of full-file linear reads:
+
+```bash
+# broad search across the project's guides (local mirror, no id needed):
+aops-cli doc scope search --project-slug aops --q "view sugar" --local --json
+aops-cli doc scope search --project-slug aops --q "filter" --local --json
+aops-cli doc scope search --project-slug aops --q "digest" --local --json
+# exact search within a known guide version:
+aops-cli doc search --document-version-id <docver-id> --q "view sugar" --local --json
+# section tree of a known guide version (hosted-only — no local fallback):
+aops-cli doc outline get --document-version-id <docver-id> --json
+```
+
+There is no `aops-cli docman … --slug` command — use the ladder; reference sections by document title + section name + keywords, not bare numbers.
+
+For flag-level detail per command, always run `--help` first:
+
+```bash
+aops-cli view --help
+aops-cli view dashboard --help
+aops-cli view hosted-projects --help
+aops-cli view hosted-inventory --help
+aops-cli view sprint --help
+aops-cli view task --help
+aops-cli view board --help
+aops-cli view digest --help
+aops-cli view memory --help
+aops-cli view discussions --help
+```
+
+If `--help` and this skill disagree, **`--help` wins** (canonical command surface). If `.aops/docman/aops-guides/aops-cli-user-guide.md` and this skill disagree, **user guide wins**.