@aopslabs/aops 0.2.0

package/LICENSE

@@ -0,0 +1,19 @@
+AOPS PROPRIETARY SOFTWARE NOTICE
+
+Copyright (c) 2026 Mehmet Zeki Sönmez. All rights reserved.
+
+This software, its source code, documentation, and associated materials are
+proprietary and confidential. Possession of, access to, or receipt of these
+materials does not grant any license or other right.
+
+Use, reproduction, modification, distribution, hosting, sublicensing, or other
+exploitation is permitted only to the extent expressly authorized by a written
+agreement executed by the applicable AOPS rights holder. A customer agreement
+may incorporate the unmodified Bonterms Software License Terms, Version 1.0,
+through an executed Cover Page and applicable Order.
+
+Bonterms Software License Terms, Version 1.0:
+https://bonterms.com/forms/software-license-terms-v1
+
+Third-party components remain governed by their respective license terms. See
+THIRD_PARTY_NOTICES and the applicable dependency inventory.

package/NOTICE

@@ -0,0 +1,7 @@
+AOPS
+
+Copyright (c) 2026 Mehmet Zeki Sönmez. All rights reserved.
+
+Private and confidential commercial software. No open-source license is granted
+for AOPS first-party code. See LICENSE for the controlling proprietary notice
+and THIRD_PARTY_NOTICES for third-party attributions.

package/README.md

@@ -0,0 +1,203 @@
+# @aopslabs/aops
+
+AOPS CLI and terminal setup application. It can connect to a remote AOPS Server
+without installing a local Server, or manage a separately installed local
+Server.
+
+```sh
+npm install --global @aopslabs/aops
+aops --help
+aops setup
+aops setup ai
+aops setup guide
+aops setup init
+aops cockpit
+aops assets
+```
+
+For a local installation, install the Server package separately:
+
+```sh
+npm install --global @aopslabs/aops @aopslabs/aops-server
+```
+
+The source repositories remain private. Customer-required runtime dependencies
+may also be published as public npm packages so ordinary installation never
+needs private registry credentials; this does not grant an open-source license.
+
+The former npm package line is frozen at `@aopslab/aops-cli@0.1.15`. Do not
+publish later CLI versions under that package name.
+
+`aops` is the primary executable. The `aops-cli` executable remains an exact
+backward-compatible alias, while new npm releases use the `@aopslabs/aops`
+package name. `aops cockpit` opens a healthy installed Cockpit,
+starting safely stopped services first; use `--no-open --json` on headless
+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`.
+
+Parameterless `aops` opens the bundled Rust TUI. Commands such as `aops setup`,
+`aops server status`, and `aops --help` retain the existing CLI behavior.
+When stdin or stdout is not an interactive terminal, parameterless `aops`
+prints short CLI guidance instead of trying to draw the TUI.
+`aops setup` always opens the installation menu, and `aops setup ai` prints a
+safe prompt that can be handed to Codex, Claude, or another terminal AI agent.
+The prompt routes the agent to the packaged `aops-install` skill and keeps
+secrets in masked AOPS prompts instead of chat or argv.
+
+The default `trusted-local` server remains bound only to
+`127.0.0.1:5900`. It does not trust LAN or Tailscale interfaces. AOPS Server
+on `5900` and Cockpit on `5922` are independently supervised services, and
+neither redirects to the other. Community no longer embeds a non-loopback
+identity provider, password store, refresh-session runtime, or first-admin
+bootstrap. Repair a legacy local environment without putting its PostgreSQL
+URL in argv:
+
+```sh
+AOPS_PG_URL='<private-url>' aops setup server-env --auth trusted-local \
+  --yes --json
+```
+
+The managed block is rewritten as `trusted-local`; retired JWT, encryption,
+and bootstrap keys are removed without being printed. Local setup exposes one
+security mode: `trusted-local` with `loopback`. Remote identity is owned by
+South and consumed only as a separate CLI target using `remote-session`.
+External targets require HTTPS and `system-ca`; plain HTTP has no remote
+exception.
+
+```sh
+aops target add --name remote --api-base-url https://aops.example.com \
+  --auth-provider remote-session --tls-policy system-ca --apply
+aops target doctor remote --json
+aops target use remote --apply
+aops auth login --target remote
+aops auth status --target remote
+aops auth logout --target remote
+```
+
+For one compatibility release, target configuration input
+`authv2-jwt-session` is accepted and immediately canonicalized to
+`remote-session`; persisted current configuration uses only the canonical
+name. Existing local AuthV2 tables remain historical/read-only. Use
+`aops auth legacy-export` for a credential-free deterministic identity and
+role export; every migrated user must authenticate again through South.
+
+`aops auth logout --target remote --local-only` deliberately clears only the
+local encrypted credentials when remote revocation is unavailable.
+
+`aops setup init` is the normal cross-platform first-install wizard. It offers an
+existing PostgreSQL connection, an automatic Docker PostgreSQL 17 container,
+or a dedicated AOPS role/database created in PostgreSQL installed on this computer,
+uses the standard `default` instance with server port `5900` and Cockpit port
+`5922`, installs all registered
+runtime pointers, reconciles the bundled signed official catalog without
+activating its skills, and leaves starter/demo user data untouched. Setup may
+reconcile only the catalog's required internal state. Managed PostgreSQL uses a
+generated strong password by default, with a masked custom-password choice in
+the interactive wizard. All
+database paths verify migrations before readiness; interactive terminals show
+animated progress and `--json` remains machine-clean. Interactive setup applies
+the chosen path immediately after collecting its required private inputs; the
+verified global AOPS core/runtime gateways are automatic and have no extra
+selection or confirmation questions. Signed collaboration
+and working-discipline packages are imported as discoverable catalog choices,
+not silently activated. Use `--agent-assets skip` only for an explicit opt-out.
+A managed database can be
+removed only with `aops server reset --remove-managed-postgres
+--confirm-data-loss --confirm-instance default`; exact ownership labels are
+verified before the container or volume is deleted.
+
+Every JSON setup preview includes a deterministic, mutation-free installer
+contract. `installerPlan.contractVersion` must be exactly
+`aops.setup-installer-plan/v2`, `installerPlan.operation` identifies the
+lifecycle action, and `installerPlan.planId` binds both fields plus the exact
+selection and readiness material. Human clients such as AOPS TUI reject an
+unsupported contract or operation before applying, then pass the identity back
+with `--plan-id`. A changed contract, source, selection, or readiness snapshot
+therefore fails before setup mutates anything. Existing scripts may still use
+the legacy direct `--apply` form, while new automation should validate the
+contract and bind preview and apply explicitly:
+
+```sh
+aops setup init --path 2 --yes --json
+aops setup init --path 2 --plan-id sha256:<64-hex> --apply --yes --json
+```
+
+Setup path `4` connects the CLI to an existing AOPS Server without installing
+or operating local PostgreSQL or server processes. It saves and selects the
+named target, checks that exact endpoint, and continues with the browser-approved
+remote-session device login when required:
+
+```sh
+aops setup init --path 4 \
+  --api-base-url https://aops.example.com \
+  --target-name remote \
+  --target-auth-provider remote-session \
+  --target-tls-policy system-ca
+```
+
+Setup path 3 probes loopback PostgreSQL without relying on `psql` being on
+`PATH`, then asks for an existing administrator role/password through masked
+input. The administrator password is transient; AOPS stores only its generated
+application connection in the private user server-env. If PostgreSQL is absent
+or stopped, readiness returns platform-specific Windows, macOS, or Linux
+install/start guidance instead of silently invoking an elevated package manager.
+
+The existing-PostgreSQL path supports managed providers such as Supabase and
+Neon. Readiness compares only the migration-derived AOPS-owned table, column,
+key, constraint, and index contract; column order, audit timestamps, local
+receipts, and unrelated provider objects do not affect the result. The five
+domain migration roots (`sys`, `agentspace`, `docman`, `projectman`, and
+`chatv3`) remain resumability evidence rather than a second schema authority.
+When that semantic structure is already exact, readiness does not inspect
+historic SQL or journal bytes; executable bundle validation occurs only when
+pending DDL must run.
+Provider schemas, extensions, global event triggers, and unrelated `public`
+objects are preserved. Normal setup does not require backup evidence, hash
+application rows, pre-lock AOPS tables, or rewrite provider-managed grants.
+Eligible DDL runs transactionally under a non-waiting migration lock and the
+live semantic schema is read back before success. Optional audit-write failure
+does not invalidate that result.
+
+The CLI package does not force-install `@aopslabs/aops-server`. Remote users need
+only the CLI; local users install the matching Server package separately. No
+customer path requires Git or a source checkout. Advanced developers can still
+run an explicit checkout with `--source-root`.
+A stopped installation can move between valid checkout/npm roots through the
+same setup command without reset or duplicate rollback copies; same-root npm
+byte drift still requires reinstalling the package.
+
+`aops setup guide` prints the packaged agent-readable installation skill before
+the server is initialized. `aops assets` opens the registered-runtime asset
+manager. It installs or updates the verified AOPS Gateway skill, repairs global pointers, reports
+status, and can safely remove recognized pointers while retaining the local
+verified core. Interactive `aops setup init` applies directly; automation uses
+an explicit path with `--apply --yes`.
+The official npm package supplies an independently signed
+Gateway/client-core closure and inert official catalog snapshot, so normal
+installation does not depend on an application-image release or ask for a
+release directory. `--from-release` remains an
+advanced maintainer/offline override. Use `aops assets --help` for the
+non-interactive commands and target selectors. Unknown or user-owned skill
+files are never overwritten or removed. Use `--target all`, a single runtime,
+a comma-separated subset, or repeated `--target`; `both` is not supported.
+
+Server data, configuration, credentials, logs, and lifecycle state are stored
+outside npm's package directory. Existing and manually created PostgreSQL
+remain operator-owned; setup path 2 owns only its namespaced, label-verified
+managed PostgreSQL resources.
+
+Opening the TUI does not by itself start or stop either service. Use the TUI's
+explicit actions or the CLI command families. The convenience
+`aops cockpit` command may start safely stopped services before opening the
+browser; the explicit server and Cockpit lifecycle commands never stop or
+start the other service.
+
+The npm package includes `launchers/aops-server.sh` and
+`launchers/aops-server.ps1` for running the installed server in the current
+terminal with live logs. They invoke `node dist/launchers/server.js` by a
+package-relative path, reuse the normal installed lifecycle, and stop on
+Ctrl+C or terminal close. `launchers/aops-cockpit.sh` and `.ps1` invoke the
+separate `node dist/launchers/cockpit.js` entry and start only Cockpit. The
+scripts accept `--instance` and `--data-root`; they contain no credentials and
+do not resolve or invoke `aops` through `PATH`.

package/assets/agent-assets/core/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/assets/agent-assets/core/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/assets/agent-assets/core/references/aops-cli-core/SKILL.md

@@ -0,0 +1,108 @@
+---
+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
+```
+
+`aops setup init` owns the complete first-run flow: choose 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. Database secrets belong only in masked prompts 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`: non-interactive input handling; 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/assets/agent-assets/core/references/chatv3/SKILL.md

@@ -0,0 +1,48 @@
+---
+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 masked CLI prompts or supported input-file/env mechanisms.
+
+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/assets/agent-assets/core/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/assets/agent-assets/core/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.