@aopslabs/aops 0.3.31 → 0.3.32

package/assets/agent-assets/core/user-guides/aops-system.md

@@ -1,102 +0,0 @@
-# AOPS Community system guide
-
-AOPS consists of a server, a CLI, independent domain capabilities, and optional monitoring surfaces.
-
-- `aops-server` hosts the installed domains and is canonical for their records.
-- the `aops` CLI provides setup, target/auth configuration, domain sugar, generic discovery/invoke, and local client-asset lifecycle commands.
-- Domain plugins own their semantics and operation schemas.
-- Cockpit applications are optional presentation and monitoring surfaces.
-
-The server and CLI need not be on the same computer. A local client selects a target and keeps credentials in its user-level configuration. Repository `.aops` content binds a project and caches derived views; it does not replace hosted records or the verified user-level agent-assets store.
-
-## Installation boundary
-
-`aops setup init` is the setup authority. It can use an operator-supplied
-PostgreSQL URL, manage only an AOPS-owned Docker PostgreSQL, or create a
-dedicated AOPS role/database in loopback PostgreSQL already installed on the
-computer. All server paths use the same migration verification. PostgreSQL
-administrator credentials for local provisioning are transient and never
-stored; the application connection is kept in the private user server-env.
-Use `aops setup guide` for the small installation skill and live
-`aops setup init --help` for exact flags.
-
-Successful default setup also installs or repairs the signed global AOPS
-gateway for every registered agent runtime. Its offline core provides a
-token-efficient router plus rich, on-demand guides for the mounted Community
-domains and available working disciplines. A discipline is never selected or
-activated automatically.
-
-After local setup, invoking `aops` without arguments shows the operator home
-without starting or stopping either local service. Use the separate Server and
-Cockpit controls when you want to change their process state.
-
-The installed CLI also ships direct `.sh` and `.ps1` launchers. The server
-launcher runs the normal installed lifecycle in the current terminal with live
-logs and Ctrl+C cleanup. The Cockpit launcher starts only its independent
-background process. Both call package-relative Node entrypoints and never
-carry database secrets in the script or argv.
-
-## Guarded global update
-
-The bundled Rust TUI has an Update page for an already installed npm-based
-AOPS system. Its Check action is read-only. Prepare downloads and verifies the
-exact public candidate and restore tarballs and writes a plan without changing
-services or packages. Apply requires that exact plan, briefly stops Cockpit
-and Server, installs one global `@aopslabs/aops` CLI with its exact nested
-Server dependency, and repeatedly verifies direct Server, Cockpit, and
-Cockpit-proxy health. Failure automatically restores the prior exact versions,
-package layout, and services.
-
-The same lifecycle is available headlessly:
-
-```text
-aops update check --json
-aops update prepare --json
-aops update apply --plan <update-plan.json> --confirm <sha256-plan-id> --json
-```
-
-CLI versions released before candidate-owned execution cannot retroactively
-load the safer apply implementation. For that one transition, let the
-installed old CLI run `prepare`, then launch the exact target package outside
-the global installation and use its explicit bridge command. macOS/Linux:
-
-```text
-npm exec --yes --registry=https://registry.npmjs.org --userconfig=/dev/null --package=@aopslabs/aops@<exact-target> -- aops update bridge --plan <update-plan.json> --confirm <sha256-plan-id> --json
-```
-
-Windows uses the same command with `--userconfig=NUL`. The bridge rejects the
-installed old CLI entrypoint and a candidate version that differs from the
-plan target; that external candidate then stages and re-verifies the complete
-executor closure before any global mutation. Once this transition succeeds,
-ordinary TUI and headless Apply actions use candidate-owned execution.
-
-All metadata and tarball reads are pinned to the public npm registry. A legacy
-top-level Server dedupe is treated as a repairable package-layout issue. The
-updater does not publish packages, create tags/releases, or replace the normal
-candidate acceptance and independent review gates.
-
-## Capability discovery
-
-Start with the relevant CLI family help. When a server has custom or newer domains, query its live catalog:
-
-```text
-aops agent tools --summary --json
-aops agent tools --domain <domain> --q <intent> --limit 5 --summary --json
-aops agent schema --tool <domain.operation> --summary
-```
-
-Sugar `--help` is authoritative for CLI flags. Live tool schema is authoritative for direct `agent invoke` payloads.
-
-## Composition without prescription
-
-Projectman can represent boards, tasks, sprints/plans, reviews, issues, and handoffs. These are independent capabilities: board-only, sprint-only, combined, and neither are all valid choices. The same principle applies to memory, documents, chat, task execution, and optional working-discipline assets.
-
-## Local state boundaries
-
-- user configuration selects servers and authentication;
-- the logical AOPS data root contains machine-local runtime state;
-- `agent-assets` beneath that data root contains verified immutable packages and activation/binding receipts;
-- a repository `.aops` directory contains project binding and derived cache views;
-- hosted reusable skills and prompts remain server-canonical unless an exact package is explicitly materialized.
-
-For current paths, flags, previews, apply requirements, and troubleshooting, use `aops --help` and the relevant nested help.

package/assets/agent-assets/core/user-guides/chatv3.md

@@ -1,113 +0,0 @@
-<!-- Public packaged snapshot from canonical slug:aops ChatV3 guidance. Installed command --help and live schema win on drift. -->
-
-# ChatV3 User Guide
-
-## 1 Canonical CLI surface
-
-`aops chat` is the canonical ChatV3 command tree. `aops chatv3` is retained as
-a compatibility alias and exposes the same behavior. The former Agentspace
-hosted-chat sugar is no longer projected as a second `aops chat` system.
-
-| Need | Command |
-| --- | --- |
-| Join from an invite | `aops chat join "<invite>" --handle <agent> --save-session --json` |
-| Send text | `aops chat send --session <id> --room <slug> "<text>" --json` |
-| Read once | `aops chat read --session <id> --room <slug> --after-seq <n> --json` |
-| Foreground wait | `aops chat listen --session <id> --room <slug> --after-seq <n> --timeout-sec 60 --json` |
-| Bind PM/doc refs | `aops chat binding add --session <id> --room <slug> --binding-type <type> --ref-id <id> --json` |
-| Roster/presence | `aops chat member list ...`, `aops chat presence set ...` |
-| Local sessions | `aops chat session list|get|forget ... --json` |
-
-`read` and `listen` return `messages`, `messageCount`, `latestSeq`, and
-`caughtUp`. `listen` exits `0` when it finds messages and `22` on timeout. A
-timeout is not task completion: continue bounded foreground listening while
-the room still owns active work.
-
-## 2 Agent-owned local session store
-
-ChatV3 session records include encrypted member tokens plus either E2E wrap
-material or server-managed room epoch keys. They are local credentials and
-must never appear in messages, source files, logs, PM records, or shell
-history.
-
-The default store is isolated by local agent owner under
-`~/.aops/chatv3/<owner-hash>/sessions.json`. Owner selection is:
-
-1. explicit `--session-owner <id>`;
-2. `AOPS_CHATV3_SESSION_OWNER`;
-3. detected Codex or Claude session identity;
-4. the local interactive operator identity.
-
-The raw identity is hashed before it is persisted or shown. Each owner also
-has a separate encryption key file. Passing a store owned by a different
-agent fails closed. A legacy `~/.aops/chatv3-sessions.json` session is claimed
-once and copied into the first owner that loads it; another owner cannot claim
-that same legacy session afterward.
-
-`--store-path` remains an advanced exact-path override. Even with that
-override, the store header must match the current owner.
-
-## 3 Cursor safety
-
-Use `read` or `listen` to consume messages and then advance delivered/read
-cursors to the highest message actually returned.
-
-`send --mark-delivered --mark-read` is guarded. Before sending, the CLI reads
-the current member receipt. It advances to the sent sequence only when the
-previous cursor is exactly `sentSeq - 1`. If another message arrived in the
-gap, the message is still sent but `result.cursorAdvance` reports
-`unseen_message_gap` and the cursor is not advanced. Read the missing range,
-then mark it explicitly. This prevents a concurrent sender from making an
-unseen peer message appear read.
-
-## 4 Encryption modes and invites
-
-| Mode | Cipher suite | Invite fragment | Content access model |
-| --- | --- | --- | --- |
-| `e2e` | `v0-shared-epoch` | `#<keyId>.<accessSecret>.<wrapSecret>` | server-blind content; clients require wrap/recovery material |
-| `server-encrypted` | `v1-server-managed` | `#srv.<keyId>.<accessSecret>` | server-managed encryption; server can access message content |
-
-Cockpit creates `server-encrypted` channels by default and offers `e2e` as the
-stricter client-managed option. Documentation must not describe
-`server-encrypted` as E2E.
-
-Removing a member blocks future member-auth reads, re-mint, and managed epoch
-key reads. It cannot erase material already fetched by that member; rotate keys
-when stronger post-removal secrecy is required.
-
-## 5 Coordination boundaries
-
-ChatV3 messages wake and coordinate agents. Durable execution/review truth
-lives in Projectman; structured design stances and conclusions live in
-`aops discuss`; durable narrative handoff belongs in memory. Bind the relevant
-PM, Docman, Discuss, or repository reference to the room, and include the same
-reference in review requests/results.
-
-Room summaries expose source messages only as summarization input. Persist an
-abstractive digest plus refs and sequence range, never a verbatim transcript.
-
-## 6 Membership and Cockpit
-
-Members are `active` or `removed`; standard roles are `owner`, `member`,
-`operator`, and `observer`. Presence is room-scoped and uses `active`, `idle`,
-`working`, `reviewing`, `blocked`, or `offline`.
-
-Participation is room-scoped on servers with the room-members feature: a new
-room starts with only its creator; joining a channel binds you to the
-`general` room only. You become a participant of another room by sending a
-message there or with `aops chat room join --session <id> --room <slug>`
-(presence alone does not join a roster). `room leave` detaches you (disjoin;
-re-join any time);
-`room members` lists active participants by default (`--status
-left|removed|all` for the rest). The room
-creator or a channel owner/operator can kick with `member remove --member
-<id> --room <slug>` and re-add with `member restore --member <id> --room
-<slug>`; a room-level kick is sticky (self re-join is rejected) and blocks
-sending, but it does not touch channel membership. Note: kicks do not revoke
-already-fetched crypto material — rotate the channel for that.
-
-`aops chat leave` is the channel-level self-removal path. Owners/operators
-may remove other
-active members. Cockpit must keep bearer/member tokens out of local storage
-and visible text, expose room guidance and cursor state, and preserve honest
-copy for each encryption mode.

package/assets/agent-assets/core/user-guides/docman.md

@@ -1,223 +0,0 @@
-<!-- Public packaged snapshot from Docman domain user guide. Read only the relevant section; installed command --help and live schema win on drift. -->
-
-# Docman User Guide
-
-Docman keeps canonical written knowledge organized, searchable, versioned, and
-available to both people and AI agents. Documents live on the hosted server
-rather than being scattered across local files and chat sessions.
-
-## Ownership
-
-- Projectman owns current execution plans and task status.
-- Agentspace owns durable working context and reusable agent assets.
-- Docman owns canonical written knowledge and its version history.
-- Operator-owned storage owns file bytes and recovery lineage.
-
-References can connect these domains without duplicating their source of truth.
-
-## Document Structure
-
-Docman separates identity, versions, and composition:
-
-```text
-group -> document -> document version
-                   -> section -> ordered page link -> page -> page version
-```
-
-Snippets, embeds, and assets can be linked into pages. This structure allows a
-document to evolve without silently rewriting earlier published versions.
-
-## Help-First Discovery
-
-Use the installed CLI help because command flags and available operations may
-change between versions:
-
-```bash
-aops doc --help
-aops doc group --help
-aops doc --help
-aops doc version --help
-aops doc section --help
-aops doc page --help
-aops doc search --help
-aops doc answer --help
-aops doc mirror --help
-```
-
-For raw hosted operations, inspect the schema first:
-
-```bash
-aops agent tools --domain docman
-aops agent schema --tool docman.document.create
-```
-
-Do not infer raw payload fields from sugar CLI flags.
-
-## Create and Organize Knowledge
-
-The normal authoring flow is:
-
-1. Create or select a document group.
-2. Create the document identity and metadata.
-3. Create an immutable document version.
-4. Add sections for the intended reading structure.
-5. Create pages and page versions.
-6. Link pages to sections in explicit order.
-7. Set current versions after the content is reviewed.
-
-Read the relevant help before each write. Prefer small CRUD operations over a
-large import when making targeted changes.
-
-## Versioning
-
-Versions are immutable snapshots of authored content. To revise content:
-
-1. read the current version
-2. create a new version with the intended change
-3. validate the new content and links
-4. set the new version as current
-
-This preserves what readers and agents saw previously and makes publication
-history auditable.
-
-### Review evidence for mutable drafts
-
-Before requesting review, compose or materialize the exact candidate and keep
-the returned version identifiers and `contentHash`. Record one complete
-immutable evidence reference in the Projectman review request, for example:
-
-```text
-docman:page-version:<id>#contentHash=sha256:<digest>
-```
-
-An approved review result repeats the exact same reference. Saving the draft
-again changes the content hash; the earlier result remains historical evidence
-for the old content and a linked re-review is required for the new hash. A
-mutable page-version id without its content hash is not sufficient approval
-evidence.
-
-## Sections and Pages
-
-Sections provide navigation and grouping. Pages hold readable content. Ordered
-link records determine which pages appear in a section and in what order.
-
-Do not assume that creating a page automatically places it in a document. The
-page must be linked into the appropriate section. Likewise, a document version
-does not implicitly replace page versions.
-
-## Exact Text Files
-
-Docman also supports UTF-8 text files such as `.cs` and `.txt`. The persisted
-profile is explicit:
-
-- `contentMode=structured` uses the normal section/page graph and `.md` mirror
-- `contentMode=text-file` has exactly one root page, no sections, and no second page
-- `page-version.format` describes source syntax (`text`); `fileExtension`
-  describes the lowercase/path-safe file identity (`cs`, `txt`)
-
-Uppercase extensions are rejected instead of normalized. Do not infer or fix an
-extension from file content.
-
-Save an immutable source snapshot with the final operation/sugar surface:
-
-```bash
-aops doc source-file save \
-  --document-id <document-id> \
-  --extension cs \
-  --source ./device-control.cs \
-  --expected-version-id <current-version-id> \
-  --expected-content-hash <current-source-hash> \
-  --publish-now \
-  --apply \
-  --json
-```
-
-The operation id is `document.source-file.save`; the earlier design name
-`document-version.source-file.put` is not supported. Exact source materializes
-with `doc publish --target source`. Cockpit selects an escaped monospace
-renderer from the returned metadata, hides the outline, and offers wrap, copy,
-and download using the persisted suggested filename.
-
-## Search and Answer
-
-Docman indexes hosted content so agents can retrieve only the material relevant
-to a task. Search returns matching sources. Answer operations produce a
-deterministic response with evidence pointing back to canonical records.
-
-When using a result:
-
-- retain the source document/page/version identifiers
-- reopen the exact version when accuracy matters
-- distinguish retrieved evidence from an agent's inference
-- avoid copying the answer into another canonical store without a reason
-
-## Markdown Import
-
-Markdown is useful for initial migration or a guarded baseline. It is not a
-second long-term source of truth.
-
-Before import:
-
-- identify the target group and document
-- confirm whether the import creates or revises content
-- inspect baseline/version guards
-- preview the resulting structure when supported
-
-After import, author subsequent canonical changes through Docman and export or
-refresh mirrors as projections.
-
-## Publish and Export
-
-Publication creates a readable projection of approved hosted content. Markdown
-export makes documents portable for distribution or repository consumption.
-Neither flow transfers canonical ownership away from Docman.
-
-## Read-Only Mirrors
-
-Repositories may keep a read-only mirror for local agent context:
-
-```bash
-aops doc mirror pull \
-  --project-slug <project> \
-  --group-uid <group> \
-  --out-dir ./.aops/docman \
-  --apply \
-  --json
-```
-
-Mirrors must not be hand-edited and pushed back. Make the canonical change on
-the hosted server, then pull the mirror again.
-
-There are two compatible mirror profiles:
-
-- doc-mirror-v2 preserves existing structured/legacy `.md` behavior
-- doc-mirror-v3 writes text-file source as raw `<slug>.<ext>` plus adjacent
-  `<slug>.<ext>.docman.json`, with no injected frontmatter/comments
-
-For v3, guarded push is an explicit authoring action: it validates sidecar
-identity, project/scope, version/hash, extension, exact UTF-8, and NUL safety
-before creating a new immutable snapshot. A structured version with an explicit
-non-`md` extension is rejected: no structured mirror path migration contract
-exists yet, and silently ignoring the persisted extension would be unsafe.
-
-## Raw Invoke Fallback
-
-If a sugar command fails because its wrapper no longer matches a strict hosted
-schema, stop trying guessed flag combinations. Inspect the operation contract:
-
-```bash
-aops agent schema --tool docman.<operation-id>
-aops agent invoke --tool docman.<operation-id> --input @input.json --apply
-```
-
-Use raw invocation only as a bounded workaround and record the sugar defect for
-repair.
-
-## Agent Guidance
-
-- Retrieve the smallest relevant content set.
-- Preserve source and version references in decisions and handoffs.
-- Create a new version instead of mutating historical content.
-- Keep execution status in Projectman and session context in Agentspace.
-- Treat local mirrors as read-only projections.
-- Validate links and current-version pointers before publishing.

package/assets/agent-assets/core/user-guides/projectman.md

@@ -1,233 +0,0 @@
-<!-- Public packaged snapshot from Projectman domain user guide. Read only the relevant section; installed command --help and live schema win on drift. -->
-
-# Projectman User Guide
-
-This guide explains how operators and AI agents use Projectman through the
-hosted `aops pm` surface. Projectman is the source of truth for current
-planning and execution status.
-
-## Mental Model
-
-```text
-board
-  -> kanban task
-       -> sprint
-            -> phase
-                 -> microtask
-```
-
-- The board makes delivery visible.
-- The kanban task represents the work item.
-- The sprint is the task-scoped implementation plan.
-- Phases organize the plan.
-- Microtasks track the smallest verifiable units of work.
-
-Durable session context belongs in Agentspace memory. Canonical long-form
-knowledge belongs in Docman. Projectman records what is being delivered, its
-state, its evidence, and its review lineage.
-
-## Help-First Discovery
-
-Read the exact command surface before writing:
-
-```bash
-aops pm --help
-aops pm board --help
-aops pm ktask --help
-aops pm sprint --help
-aops pm utask --help
-aops pm issue --help
-aops pm feedback --help
-aops pm review-request --help
-aops pm handoff --help
-```
-
-Use sugar commands for routine work. For raw operation invocation, inspect the
-hosted schema first:
-
-```bash
-aops agent tools --domain projectman
-aops agent schema --tool projectman.kanban-task.create
-```
-
-## Select the Project
-
-Projectman writes are project-scoped. Bind the repository or pass the exact
-project selector required by the installed CLI. Confirm the active project
-before mutating a board, task, or sprint.
-
-## Boards
-
-Create a board when the project does not already have an appropriate delivery
-surface:
-
-```bash
-aops pm board create --name "Delivery" --apply
-aops pm board list --json
-```
-
-A board contains ordered columns. Board lifecycle actions can initialize or
-resume a working board, but closing a board is an operator decision.
-
-## Kanban Tasks
-
-Create a task before implementation starts:
-
-```bash
-aops pm ktask create \
-  --board delivery \
-  --column Todo \
-  --title "Implement the selected capability" \
-  --apply
-```
-
-The task is the visible delivery item. Keep its state honest: moving a task to
-Done should follow implementation and validation, not intention.
-
-Useful reads:
-
-```bash
-aops pm ktask list --board delivery --json
-aops pm ktask get --task <task-id> --json
-```
-
-## Sprints and Implementation Plans
-
-Create a sprint under the kanban task. State what will change, why it matters,
-and how completion will be verified:
-
-```bash
-aops pm sprint create \
-  --task <task-id> \
-  --name "Capability implementation" \
-  --goal "NE: deliver the capability; NICIN: make the workflow usable; DONE-WHEN: tests and live verification pass" \
-  --apply
-```
-
-The `aops plan` surface is a facade over this sprint plan. It does not create
-a second plan store.
-
-Use microtasks for bounded, verifiable steps. Update each item individually so
-the sprint remains a trustworthy execution record:
-
-```bash
-aops pm utask create --sprint <sprint-id> --title "Implement" --apply
-aops pm utask create --sprint <sprint-id> --title "Validate" --apply
-aops pm utask update --id <microtask-id> --status doing --apply
-aops pm utask update --id <microtask-id> --status completed --apply
-```
-
-Inspect `aops pm utask --help` for the exact phase and ordering flags in the
-installed version.
-
-## Issues and Feedback
-
-Use issues for defects, blockers, or follow-up work that must remain visible.
-Use feedback for operator observations and requested improvements. Preserve the
-link to the task, sprint, or review that produced the item.
-
-```bash
-aops pm issue --help
-aops pm feedback --help
-```
-
-Feedback can become tracked work without losing its origin. Do not copy the
-same concern into unrelated records without retaining lineage.
-
-## Review Requests
-
-Review requests coordinate synchronous or asynchronous review between agents or
-operators. The implementation remains attached to its Projectman context, and
-review results are appended rather than overwritten.
-
-```bash
-aops pm review-request --help
-```
-
-A reviewer can approve, comment, or request changes. When changes are requested:
-
-1. keep the original result intact
-2. update the implementation task and sprint
-3. record the new evidence
-4. create or continue the linked re-review flow
-
-When the reviewed candidate is a mutable Docman draft, the review request must
-carry the exact composed evidence reference: document/page version ids together
-with `contentHash=sha256:<digest>`. An approved result repeats that full
-reference exactly. If the draft is edited, its hash changes and the previous
-approval no longer covers the new content; keep the old result and open a
-linked re-review.
-
-Chat can wake or coordinate participants, but Projectman remains the review and
-execution source of truth.
-
-## Handoffs
-
-A handoff should let another agent continue without reconstructing the entire
-session. Include:
-
-- what changed
-- what was validated and with which evidence
-- what remains open
-- the exact next action
-- relevant task, sprint, issue, review, document, or artifact references
-
-Use `aops pm handoff --help` for the installed command shape. Durable
-narrative context may also be written to Agentspace memory, but do not duplicate
-the active execution status in a competing store.
-
-## Reading Local Presentation Views
-
-After synchronizing the read-only cache, Projectman can be inspected through
-local views without mutating hosted state:
-
-```bash
-aops view dashboard --style agent
-aops view board <selector>
-aops view task <selector>
-aops view sprint <selector>
-aops view digest --task <selector>
-```
-
-Views do not call the server, synchronize data, or write decisions. Use normal
-`pm`, `mem`, or `discuss` commands for durable changes.
-
-## Status Discipline
-
-- `todo`: planned but not started
-- `doing`: active work
-- `completed`: implemented and honestly validated
-- blocked or cancelled states: use only when supported by the current command
-  and record the reason
-
-The `pm utask` and `pm sprint` sugar write boundaries accept `done` and
-`complete` as human-facing aliases, but always send and report the canonical
-domain status `completed`. Raw `agent invoke` payloads do not use those aliases:
-inspect the live schema and send `completed`. For kanban tasks, `Done` is a
-board-column label rather than a microtask status. Task create/move sugar
-resolves a name, slug, placement UUID, or legacy reusable column UUID to the
-selected board's canonical board-column placement UUID.
-
-`aops pm status audit` is read-only and also checks accepted review evidence.
-It reports `review_scope_dangling` once per review request when a referenced
-sprint phase or microtask no longer exists. Repair only when the logical mapping
-is deterministic; otherwise preserve the original scope and record an explicit
-historical disposition instead of inventing a replacement identity.
-
-Do not close boards, rooms, or project-level work merely because one agent turn
-ended. Ordinary closeout writes current status and a handoff, leaving shared
-surfaces open for the operator.
-
-## Raw Invoke Fallback
-
-If a sugar wrapper fails because its payload no longer matches a strict hosted
-schema, stop guessing flags. Inspect the raw contract and invoke the operation
-directly only when necessary:
-
-```bash
-aops agent schema --tool projectman.<operation-id>
-aops agent invoke --tool projectman.<operation-id> --input @input.json --apply
-```
-
-Record the sugar defect separately so the workaround does not become the normal
-workflow.