@aopslabs/aops 0.3.3 → 0.3.5

package/README.md

@@ -35,9 +35,10 @@ hosts. Explicit `aops server ...` commands operate the API on port `5900`,
 while `aops cockpit start|stop|restart|status|health|logs` independently
 operates Cockpit on port `5922`.
 
-On Windows x64, parameterless `aops` opens the bundled Rust TUI. This release
-does not include native TUI payloads for macOS or Linux; use explicit CLI
-commands such as `aops setup init`, `aops server status`, or `aops --help` there.
+On Windows x64 and native Apple Silicon macOS, parameterless `aops` opens the
+bundled Rust TUI. Intel/Rosetta macOS and Linux do not have native TUI payloads;
+use explicit CLI commands such as `aops setup init`, `aops server status`, or
+`aops --help` there.
 Explicit commands retain the same CLI behavior on every supported platform.
 When stdin or stdout is not an interactive terminal, parameterless `aops`
 prints short CLI guidance instead of trying to draw the TUI.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: aops
+description: Route AOPS Community requests to concise packaged references, current CLI help, or live tool schema without selecting a work method.
+---
+
+# AOPS Community
+
+AOPS is a self-hostable operations layer. The `aops` command installs and
+operates a local server, connects to remote servers, discovers live domain
+capabilities, and manages verified machine-local agent assets.
+
+This root skill is deliberately small. Read exactly one matching reference,
+then open only the relevant heading in its linked user guide. Working
+disciplines are available after setup, but are never selected merely because
+this gateway loaded.
+
+## Route the request
+
+| Need | Read first |
+| --- | --- |
+| install/setup, PostgreSQL, auth, server, health, sync, views, client assets | `references/aops-cli-core/SKILL.md` |
+| read-only local dashboard, sprint/task/board views, focused digest | `references/view/SKILL.md` |
+| durable memory, reusable prompts/skills/resources/artifacts, experience | `references/agentspace/SKILL.md` |
+| durable session intent and resume packs | `references/mission/SKILL.md` |
+| boards, tasks, sprints/plans, issues, feedback, reviews, handoffs | `references/projectman/SKILL.md` |
+| versioned documents, sections, links, search, answer, mirrors | `references/docman/SKILL.md` |
+| hosted coordination rooms, messages, inbox/listen/catchup | `references/hosted-chat/SKILL.md` |
+| structured multi-agent decision/consensus topics | `references/discuss/SKILL.md` |
+| encrypted ChatV3 product channels, invites, sessions, membership | `references/chatv3/SKILL.md` |
+| counters, countries, event store, rate limits | `references/sys/SKILL.md` |
+| choose or explain a working method | `references/working-disciplines/SKILL.md` |
+| run the full optional collaborative session playbook | `references/collaborative-work/SKILL.md` |
+| another installed/custom domain | `aops agent tools --domain <domain> --summary --json` |
+
+`aops chat` is hosted coordination. `aops chatv3` is the encrypted product
+channel surface. Do not merge those models. Fileman, Tasker/Runner, and the
+interactive loop are not part of the default Community capability closure;
+discover them only if the connected server actually advertises them.
+
+## Authority order
+
+1. Packaged references explain ownership, safety, and common examples.
+2. Current nested `aops ... --help` owns sugar command flags.
+3. `aops agent schema --tool <domain.operation> --summary --json` owns raw invoke payload fields.
+4. `aops agent invoke --tool <domain.operation> --input '@payload.json' --preview --json` is the generic fallback.
+
+Use `aops agent tools --summary --json` when the installed server differs from
+the packaged core. Do not load every reference or whole guide into context, and
+do not infer server topology or capabilities from a repository checkout.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/references/agentspace/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: aops-cli-agentspace
+description: Use for durable memory, synopsis, reusable prompts/skills/resources/artifacts, experience, agent profiles, and other Agentspace-owned context through the AOPS CLI.
+---
+
+# Agentspace
+
+Agentspace owns durable agent/operator context and reusable hosted assets.
+Project execution belongs to Projectman; versioned documents belong to Docman.
+Hosted coordination and structured decisions have their own references.
+
+Read only the needed section of `../../user-guides/agentspace.md`. Exact flags
+come from live nested help.
+
+## Durable memory
+
+```bash
+aops mem --help
+aops mem list --json
+aops mem search --q "migration decision" --limit 10 --json
+aops mem write --mode resume --subject project --content "<bounded handoff>" --apply
+aops mem list --durability sticky --json
+aops mem synopsis --subject project --json
+```
+
+Use memory for decisions, constraints, handoffs, and facts that must survive a
+session. Keep content concise and scoped. Do not use memory as a duplicate task
+tracker or paste secrets, logs, or large documents into it.
+
+## Reusable hosted assets
+
+```bash
+aops prompt list --json
+aops skill list --json
+aops resource list --json
+aops artifact list --json
+aops exp list --json
+```
+
+Create/update/version commands are guarded writes. Inspect their help first:
+
+```bash
+aops skill version create --help
+aops skill version publish --help
+aops prompt version create --help
+aops resource create --help
+```
+
+Hosted prompt/skill truth lives on the server. Local mirrors are read-only
+context. Artifact records are metadata/pointers, not a large binary store.
+
+## Missions and sessions
+
+For durable session intent and resume packs, load `../mission/SKILL.md` rather
+than the full Agentspace guide. For rooms/messages load
+`../hosted-chat/SKILL.md`; for structured consensus load
+`../discuss/SKILL.md`.
+
+## Raw discovery fallback
+
+```bash
+aops agent tools --domain agentspace --q memory --limit 20 --summary --json
+aops agent schema --tool agentspace.<operation> --summary --json
+aops agent invoke --tool agentspace.<operation> --input '@payload.json' --preview --json
+```
+
+Always inspect schema before raw writes. Use `--apply` only after scope and
+payload are clear; use an idempotency key for retryable mutations when
+supported. Read back the exact record after mutation.
+
+## Boundaries
+
+- Planning, tasks, sprints, issues, feedback, reviews: Projectman.
+- Document graphs, page content, publish/search/answer: Docman.
+- Hosted coordination/wake: `aops chat`.
+- Structured decision transcript: `aops discuss`.
+- Encrypted product channel: `aops chatv3`.
+- Repo `.aops/**`: derived cache, never the canonical authoring source.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/references/aops-cli-core/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: aops-cli-core
+description: Use for AOPS installation, PostgreSQL setup, server lifecycle, health, authentication, sync, views, verified agent assets, and schema-first capability discovery.
+---
+
+# AOPS CLI core
+
+Use the installed `aops` command as runtime truth. Read only the matching
+section in `../../user-guides/aops-cli.md`, `../../user-guides/aops-system.md`,
+or `../../user-guides/agent-assets.md` when this quick map is insufficient.
+
+## Install and diagnose
+
+```bash
+aops --version
+aops setup init
+aops setup ai
+aops setup guide
+aops server status --json
+aops server health --json
+aops cockpit
+```
+
+Parameterless `aops` opens the Rust TUI for operator-led first-run choices.
+`aops setup init` is its argument-driven engine for an existing PostgreSQL,
+AOPS-managed PostgreSQL container, detected local PostgreSQL, or a remote AOPS
+server. Local server paths plan/apply/verify migrations, start the npm server,
+leave starter/demo user data untouched, and install verified agent assets. The
+CLI never opens a menu or asks a question. Database secrets belong only in TUI
+private fields or private input files/environment; never paste them into chat
+or argv.
+
+For an unattended run, inspect readiness before apply:
+
+```bash
+aops setup init --path 1 --yes --json
+aops setup init --path 2 --yes --json
+aops setup init --path 3 --yes --json
+```
+
+Use the exact next action returned by readiness. Do not bypass TLS choices,
+asset ownership conflicts, or migration lineage errors.
+
+## Server and target lifecycle
+
+```bash
+aops server start --json
+aops server stop --json
+aops server restart --json
+aops server logs --tail 100
+aops host health --json
+aops host diagnostics --json
+aops target list --json
+aops target doctor <name> --json
+```
+
+Use `aops server <command> --help` before reset, rollback, or recovery. Never
+remove operator-owned PostgreSQL/Docker resources. Setup path 2 may manage only
+its exact label-verified AOPS container and volume.
+
+## Verified agent assets
+
+```bash
+aops assets status --verify quick --json
+aops assets install --target all --apply --json
+aops assets resolve --gateway aops --json
+aops assets discover --query "sprint planning" --limit 5 --json
+```
+
+`--target all` means every registered runtime, not only Codex and Claude.
+Install/repair fails closed on unknown user files. The core makes rich guides
+and disciplines available but never selects a working method.
+
+## Cache and read-only views
+
+```bash
+aops sync status --json
+aops sync pull --apply --json
+aops view dashboard --style agent
+aops view digest --task <task-id> --depth deep
+```
+
+Hosted records remain canonical. Repository `.aops/**` content is a read-only
+cache/presentation surface; never hand-edit it as hosted truth.
+
+## Capability discovery
+
+```bash
+aops agent tools --summary --json
+aops agent tools --domain <domain> --q <intent> --limit 10 --summary --json
+aops agent schema --tool <domain.operation> --summary --json
+aops agent invoke --tool <domain.operation> --input '@payload.json' --preview --json
+```
+
+Use sugar when nested `--help` exposes it. Direct invoke requires live schema.
+If a write is intended, preview when supported and add `--apply`; destructive
+operations may additionally require `--confirm`. Stop guessing after a 400 or
+validation error and inspect full schema/OpenAPI.
+
+## Guard contract
+
+- `--json`: stable automation output.
+- `--yes`: compatibility/fail-fast behavior; never implies mutation approval.
+- `--preview`: validate/plan without applying when supported.
+- `--apply`: execute a guarded write.
+- `--confirm`: acknowledge destructive scope.
+- `--idempotency-key`: make supported retries deterministic.
+
+Current nested `--help` wins over packaged examples. Live schema wins for raw
+payload fields and the live catalog wins for mounted-domain availability.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/references/chatv3/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: aops-cli-chatv3
+description: Use for encrypted ChatV3 product channels, invitations, local session context, membership, presence, epochs, and message operations through the AOPS CLI.
+---
+
+# ChatV3
+
+Use `aops chatv3` for product-facing encrypted channel/session operations.
+This is different from `aops chat`, which owns hosted agent coordination,
+wakes, inbox cursors, and room bindings.
+
+Read only the relevant section of `../../user-guides/chatv3.md`. Exact flags
+come from nested `--help`; direct payloads come from live schema.
+
+## Common entry points
+
+```bash
+aops chatv3 --help
+aops chatv3 channel --help
+aops chatv3 session --help
+aops chatv3 member --help
+aops chatv3 send --help
+aops chatv3 read --help
+```
+
+Typical discovery and read flow:
+
+```bash
+aops chatv3 session list --json
+aops chatv3 channels --json
+aops agent tools --domain chatv3 --summary --json
+aops agent schema --tool chatv3.channel.list --summary --json
+```
+
+ChatV3 may keep invite, member-token, and room-key context in a private local
+session store. Never paste those values into chat, logs, source files, or raw
+shell history. Use supported secure-store, input-file, or environment
+mechanisms; the CLI does not collect secrets through terminal prompts.
+
+For a write not exposed by sugar, inspect the exact live schema before invoke:
+
+```bash
+aops agent schema --tool chatv3.<operation> --summary --json
+aops agent invoke --tool chatv3.<operation> --input '@payload.json' --preview --json
+```
+
+Do not use ChatV3 as the durable Projectman review record or the structured
+`discuss` transcript. Link or summarize outcomes into the correct owner when
+durability matters.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/references/collaborative-work/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: aops-collaborative-work
+description: Use when the operator explicitly wants the full AOPS session playbook for solo work, async review, or hosted chat-room collaboration with Projectman-backed execution.
+---
+
+# AOPS collaborative work
+
+Default to `solo`. Collaboration is an operator choice, not an automatic
+requirement. Select one mode at kickoff and use
+`../working-disciplines/SKILL.md` only when a working method must also be chosen.
+
+## Compact startup
+
+```bash
+aops sync status --json
+aops view dashboard --style agent
+aops start --task "<task>" --json --out ./aops-start.md
+aops mission resume --id <mission-id> --json
+aops pm board resume --board <slug> --json
+```
+
+Use `result.promptRef.path` or the output file; do not request inline/full output
+unless the prompt body is actually needed. Ask the operator only for fields
+explicitly marked operator-owned, especially agent identities and roles.
+
+## Mode 1: solo
+
+1. Read the smallest relevant guide/help surface.
+2. Create or identify the Projectman task/plan appropriate to the work size.
+3. Implement one bounded slice.
+4. Run focused validation and read back hosted mutations.
+5. Update status/handoff; keep board/mission open unless closeout was requested.
+
+Useful reads:
+
+```bash
+aops view digest --task <task-id> --depth shallow
+aops pm issue list --status open --json
+aops pm review-request list --status open --json
+```
+
+## Mode 2: solo plus async review
+
+After implementation and local validation, create a durable review request:
+
+```bash
+aops pm review-request create --help
+aops pm review-request list --status open --json
+aops pm review-request result --help
+```
+
+The reviewer records the result in Projectman. Material findings become
+Projectman issues or bounded fix slices; chat is only the optional wake channel.
+Do not claim review completion from a message alone.
+
+## Mode 3: hosted chat room
+
+```bash
+aops chat room create --slug <slug> --title "<purpose>" \
+  --created-by <lead> --member "<lead>:<role>" \
+  --member "<peer>:<role>" --apply --json
+aops chat binding add --room-id <id> \
+  --binding-type projectman.board --ref-id <board-id> \
+  --created-by <lead> --apply --json
+aops chat room brief --room-id <id> --for <peer>
+aops chat listen --for <agent> --room-id <id> --timeout-sec 570 --json
+```
+
+Each participant owns a non-overlapping slice and reports completion with
+validation evidence. Use `aops discuss` only for a material consensus decision;
+use `aops chatv3` only when encrypted product-channel behavior is the actual
+task.
+
+## During work
+
+```bash
+aops start --reminder --task "<task>" --area <area> --json
+aops mem checkpoint --help
+aops pm status audit --help
+```
+
+Prefer the detail ladder: this skill → one family reference → nested `--help` →
+live `agent schema`. Never preload every guide. Never invent another agent's
+stance, close operator-owned surfaces, or mark work done without requested
+validation and durable status.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/references/discuss/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: aops-cli-discuss
+description: Use for a structured server-canonical design decision or consensus topic with independent turns, explicit final stances, completeness checks, and deterministic conclusion.
+---
+
+# AOPS Discuss
+
+`aops discuss` owns a durable decision transcript and conclusion. Use hosted
+`aops chat` to wake/coordinate peers and Projectman to track review/execution.
+Do not start a discussion ritual for a small reversible implementation choice.
+
+The complete owner and troubleshooting model is in the Discuss sections of
+`../../user-guides/agentspace.md`.
+
+## Start and inspect
+
+```bash
+aops discuss --help
+aops discuss start --title "<decision>" --question "<question>" \
+  --participant <agent-a> --participant <agent-b> --apply --json
+aops discuss status --id <topic> --json
+aops discuss get --id <topic> --json
+```
+
+Give every participant enough neutral context to research independently. Role
+assignment belongs to the operator; an agent must not invent or swap identities.
+
+## Record turns
+
+```bash
+aops discuss turn --topic <topic> --agent <agent> \
+  --kind statement --from-file ./turn.md --apply --json
+aops discuss wait --id <topic> --for <agent> \
+  --timeout-sec 540 --interval-sec 5 --json
+```
+
+For material design decisions, record multiple substantive non-final turns so
+tradeoffs and objections are visible. Do not use chat messages as a substitute
+for the canonical topic transcript.
+
+## Finalize safely
+
+```bash
+aops discuss turn --topic <topic> --agent <agent> \
+  --kind final-stance --from-file ./final.md --apply --json
+aops discuss status --id <topic> --json
+aops discuss conclude --topic <topic> --apply --json
+```
+
+Conclude only when every required participant has a `final-stance` and status
+reports no missing final stances. Outputs must contain real decisions and
+follow-ups, not `_TBD_` placeholders.
+
+There is no automatic bridge: explicitly reference the concluded topic from a
+Projectman task/review/issue or durable memory, then send a short hosted-chat
+wake if another agent must act.
+
+For raw operations:
+
+```bash
+aops agent tools --domain agentspace --q discuss --limit 20 --summary --json
+aops agent schema --tool agentspace.<discuss-operation> --summary --json
+```
+
+Prefer slug/ID selectors returned by creation. Treat timeouts as state to
+report, not permission to fabricate another participant's stance.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/references/docman/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: aops-cli-docman
+description: Use for Docman document groups, documents, versions, sections/pages, search, answer, publish, mirrors, markdown import, and schema-first payloads through AOPS.
+---
+
+# Docman
+
+Docman owns the versioned document graph and retrieval/publishing surfaces.
+Read the matching section of `../../user-guides/docman.md` for the complete
+model; use nested help for current flags.
+
+## Discover and read
+
+```bash
+aops doc --help
+aops doc group list --project-slug <slug> --json
+aops doc list --project-slug <slug> --json
+aops doc outline get --document-version-id <id> --titles-only --depth 0 --json
+aops doc search --document-version-id <id> --q "<query>" --json
+aops doc answer --help
+```
+
+Prefer IDs from list/get output. Search is retrieval, not necessarily the full
+page body. Use outline for structure and the supported page/version read
+surface for exact content.
+
+## Author and version
+
+```bash
+aops doc group create --help
+aops doc create --help
+aops doc version create --help
+aops doc section create --help
+aops doc page create --help
+aops doc page draft-save --help
+```
+
+Create graph nodes through CRUD commands when IDs are known. Use markdown
+import for intentional bulk import, not for a one-page edit. Every mutation is
+preview/apply guarded where supported; read back the current version after
+publishing.
+
+## Search, answer, publish, and mirrors
+
+```bash
+aops doc scope search --project-slug <slug> --q "<query>" --json
+aops doc publish --help
+aops doc mirror pull --project-slug <slug> --group-uid <group> --out-dir <dir> --apply --json
+```
+
+Mirrors are read-only projections. Change the hosted document, publish/set the
+current version as required, then refresh the mirror. `aops sync pull` does not
+replace Docman mirror pull.
+
+## Raw fallback
+
+```bash
+aops agent tools --domain docman --q document --limit 20 --summary --json
+aops agent schema --tool docman.<operation> --summary --json
+aops agent invoke --tool docman.<operation> --input '@payload.json' --preview --json
+```
+
+If sugar reports a validation error, stop varying flags blindly. Compare the
+live operation schema/OpenAPI with the wrapper payload, then use raw invoke only
+with an exact reviewed payload.
+
+Docman owns document semantics; external storage owns binary file bytes and
+recovery, Projectman owns execution status, and Agentspace owns durable agent
+memory/reusable assets.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/references/hosted-chat/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: aops-cli-chat
+description: Use for hosted Agentspace coordination rooms and direct messages, membership, bindings, messages, inbox/listen/catchup cursors, manifests, and agent onboarding briefs.
+---
+
+# Hosted AOPS chat
+
+`aops chat` is the coordination and wake channel for agents/operators. It is
+not ChatV3 encrypted product messaging, the structured `discuss` transcript,
+or the Projectman review record.
+
+Deep semantics and troubleshooting are in the hosted-chat sections of
+`../../user-guides/agentspace.md`.
+
+## Room lifecycle
+
+```bash
+aops chat --help
+aops chat room list --json
+aops chat room create --slug <slug> --title "<purpose>" \
+  --created-by <agent> --member "<agent>:<role>" --apply --json
+aops chat room get --id <id> --json
+aops chat room brief --room-id <id> --for <agent>
+aops chat room manifest --room-id <id> --json
+```
+
+Use stable agent/operator identities and explicit role keys. Room closeout is
+operator-controlled; ordinary task completion should not silently close it.
+
+## Bind durable references
+
+```bash
+aops chat binding add --room-id <id> \
+  --binding-type projectman.board --ref-id <board-id> \
+  --title "PM board" --created-by <agent> --apply --json
+aops chat room manifest --room-id <id> --json
+```
+
+Bindings orient participants; they do not move canonical truth out of
+Projectman, Docman, or Agentspace.
+
+## Messages and unread work
+
+```bash
+aops chat message send --help
+aops chat inbox --for <agent> --json
+aops chat listen --for <agent> --room-id <id> \
+  --timeout-sec 570 --interval-sec 15 --json
+aops chat catchup --for <agent> --room-id <id> --apply --summary --json
+```
+
+Send a message to wake/coordinate a peer, then use Projectman for review status
+or Discuss for a decision stance. Read cursors are per participant; acknowledge
+directives and advance cursors only after processing the message.
+
+## Schema fallback
+
+```bash
+aops agent tools --domain agentspace --q chat --limit 20 --summary --json
+aops agent schema --tool agentspace.chat-message.send --summary --json
+```
+
+Do not guess member, cursor, or binding payloads. Never put database passwords,
+auth tokens, or ChatV3 room keys into hosted room messages.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/references/mission/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: aops-cli-mission
+description: Use for a durable Agentspace mission anchor, free-form session policy, active implementation-plan reference, compact resume packs, and session handoff.
+---
+
+# AOPS Mission
+
+A mission stores durable intent and policy for a work session. Projectman
+remains the execution/review source of truth; the mission may reference an
+implementation plan but does not duplicate it.
+
+## Common flow
+
+```bash
+aops mission --help
+aops mission list --json
+aops mission create --objective "<outcome>" --apply --json
+aops mission get --id <mission-id> --json
+aops mission update --id <mission-id> --objective "<updated outcome>" --apply --json
+aops mission resume --id <mission-id> --json
+```
+
+Use `aops start --resume <mission-id> --json` when the full startup composer is
+needed. Use `mission resume` alone for a compact, deterministic context pack.
+
+## Policy and plans
+
+When a selected working discipline returns a `mission.policyJson`, persist that
+exact policy rather than inventing a parallel format:
+
+```bash
+aops mission create --objective "<objective>" \
+  --policy-json '@policy.json' --apply --json
+aops mission update --id <mission-id> \
+  --active-plan-ref <sprint-id> --apply --json
+```
+
+The active implementation-plan ref points to a Projectman sprint/plan. Vision
+or long-form design belongs in Docman. Check exact fields with nested help.
+
+## Handoff and boundaries
+
+```bash
+aops pm handoff write --help
+aops mem checkpoint --help
+```
+
+An ordinary stop records current status, validation, blockers, and the next
+safe action; it does not silently close boards, rooms, or the mission. Use
+Projectman handoff or a bounded memory checkpoint for that record. Mission
+handoff is not a separate command in this release.
+
+Do not store secrets, full logs, or a second task ledger in mission policy.
+Do not create a mission when a small one-turn operation needs no durable anchor.