@aopslabs/aops 0.3.4 → 0.3.5

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/user-guides/aops-system.md

@@ -0,0 +1,63 @@
+# 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.
+
+## 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/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/user-guides/chatv3.md

@@ -0,0 +1,113 @@
+<!-- Public packaged snapshot from canonical slug:aops ChatV3 guidance. Read only the relevant section; installed command --help and live schema win on drift. -->
+
+# ChatV3 User Guide
+
+## 1 Encryption Modes And Invite Shapes
+
+### 1.1 Overview
+
+ChatV3 channels declare `encryptionMode`:
+
+| Mode | Cipher suite | Invite fragment | Content access model |
+| --- | --- | --- | --- |
+| `e2e` | `v0-shared-epoch` | `#<keyId>.<accessSecret>.<wrapSecret>` | server-blind content; every browser needs the invite wrap secret or a recovery package |
+| `server-encrypted` | `v1-server-managed` | `#srv.<keyId>.<accessSecret>` | server-managed content encryption; the server can access message content and can reissue access for active AuthV2-bound members |
+
+Cockpit creates new channels as `server-encrypted` by default and offers `e2e`
+as the stricter client-managed option. The UI and documentation must keep the
+copy honest: `server-encrypted` is encrypted by server-managed keys, not E2E.
+
+`server-encrypted` joins use the `srv` invite form, then fetch server-managed
+epoch keys for the active member. A fresh AuthV2 login can reopen a
+server-encrypted channel by re-minting the member token when the principal is
+still bound to an active membership. `e2e` channels cannot use server remint;
+they stay locked until the browser has the invite wrap secret or account
+recovery material.
+
+Removing a member blocks future member-auth reads, remint, and server-managed
+epoch-key reads. It does not delete any raw epoch keys or messages already
+fetched by that browser before removal; use a rotate follow-up when stronger
+post-removal secrecy is required.
+
+## 2 Agent CLI Contract
+
+### 2.1 Overview
+
+Agents should use `aops chatv3` when they join or operate inside a ChatV3
+product channel.
+
+| Need | Command |
+| --- | --- |
+| Join from an invite | `aops chatv3 join "<invite>" --handle <agent> --save-session --json` |
+| Send text | `aops chatv3 send --session <id> --room <slug> "<text>" --mark-delivered --mark-read --json` |
+| Read once | `aops chatv3 read --session <id> --room <slug> --after-seq <n> --json` |
+| Wait for new messages | `aops chatv3 listen --session <id> --room <slug> --after-seq <n> --timeout-sec <n> --json` |
+| Roster | `aops chatv3 member list --session <id> --json` |
+| Presence | `aops chatv3 presence set --session <id> --room <slug> --state working --json` |
+| Leave | `aops chatv3 leave --session <id> --json` |
+| Local sessions | `aops chatv3 session list|get|forget ... --json` |
+
+`read` and `listen` always return explicit cursor state:
+
+- `messages`, including `[]` when no new messages exist
+- `messageCount`
+- `latestSeq`
+- `caughtUp`
+
+`listen` exits with `0` when messages are found and `22` on timeout. It is a
+polling primitive; server-sent events remain a UI/runtime concern.
+
+`join` uses the server URL embedded in the invite by default. `--api-base-url`
+is an explicit override for controlled local smoke tests. Join output includes a
+short orientation summary with channel, active room, room count, member count,
+recent message count, and the parsed invite mode (`e2e` or
+`server-encrypted`). When `--save-session` is used, the local session store keeps
+the member token plus either the `e2e` wrap secret or the imported
+server-managed epoch keys encrypted at rest.
+
+## 3 Member And Presence Model
+
+### 3.1 Overview
+
+Members use `MEMBER_STATUSES = active | removed` and
+`MEMBER_ROLE_KEYS = owner | member | operator | observer`.
+
+Presence uses `active | idle | working | reviewing | blocked | offline`.
+Presence is scoped to a room and is safe to expose in roster surfaces because it
+contains only member id, state, note, update time, and expiration state.
+
+## 4 Self Leave And Admin Cleanup
+
+### 4.1 Overview
+
+`chatv3.member.update` is callable with member auth but the service keeps the
+authorization boundary narrow:
+
+- a member may only update its own member row to `status: "removed"`
+- that self-leave path must not include `roleKey` or `displayName`
+- every other member update still requires `owner` or `operator`
+
+The CLI exposes the self path as `aops chatv3 leave`. Cockpit exposes both
+member self-leave and owner/operator cleanup, but the domain service remains the
+source of truth for authorization.
+
+No migration is required for self-leave because `removed` is already the
+canonical member status.
+
+## 5 Cockpit Expectations
+
+### 5.1 Overview
+
+ChatV3 cockpit clients should make the agent-oriented state visible:
+
+- channel/room orientation: active channel, active room, room count, member
+  count, message count, channel guidance, and room guidance
+- roster and presence: active/removed members, role, presence state, read/deliver
+  cursors, and directive ACK rollup
+- membership controls: current member can leave; owners/operators can remove
+  other active members
+
+ChatV3 UI must not store bearer tokens in local storage, must not expose member
+tokens in visible text, and must preserve the server-blind message-content
+boundary for `e2e` channels. For `server-encrypted` channels, UI copy must
+state that the server can access message content.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/user-guides/docman.md

@@ -0,0 +1,162 @@
+<!-- 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.
+
+## 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.
+
+## 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.
+
+## 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/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/user-guides/projectman.md

@@ -0,0 +1,212 @@
+<!-- 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
+
+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
+
+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.

package/agent-assets-release/agent-assets/core/8b06775d96e37f8aef535673b8b855c11f29042f3c70ec4f273b6df04dbe824a/files/user-guides/sys.md

@@ -0,0 +1,94 @@
+<!-- Public packaged guide derived from the mounted Community Sys catalog. Read only the relevant section; live schema wins on drift. -->
+
+# Sys User Guide
+
+Sys provides small infrastructure capabilities shared by Community domains:
+tenant-scoped counters, country lookup, event persistence, and rate-limit
+state. It is mounted on the AOPS gateway but intentionally has no separate
+`aops sys` sugar tree.
+
+## Discover the live contract
+
+```bash
+aops agent tools --domain sys --summary --json
+aops agent tools --domain sys --q counter --limit 10 --examples --summary --json
+aops agent schema --tool sys.counter.next --summary --json
+```
+
+Use `--examples` only when a small invocation shape is useful. If a compact
+schema is opaque, inspect the full schema or tool detail; never guess inner
+`body` fields after a validation error.
+
+## Countries
+
+```bash
+aops agent invoke --tool sys.country.resolve-iso2 \
+  --input '{"body":{"iso2Code":"TR"}}' --json
+aops agent invoke --tool sys.country.search \
+  --input '{"body":{}}' --json
+```
+
+Country records are shared reference data. Normalize ISO2 input to the shape
+required by the live schema and prefer lookup over duplicating country truth
+inside another domain.
+
+## Counters
+
+```bash
+aops agent invoke --tool sys.counter.get \
+  --input '{"body":{"counterKey":"inventory.item.code"}}' --json
+aops agent invoke --tool sys.counter.preview-next \
+  --input '{"body":{"counterKey":"inventory.item.code","prefix":"ITM","width":5}}' --json
+```
+
+`preview-next` does not allocate a value. `next` atomically allocates one and
+requires a guarded write:
+
+```bash
+aops agent invoke --tool sys.counter.next \
+  --input '@counter-next.json' --apply --json
+```
+
+Treat `counter.reset` as destructive. Read the live schema, inspect the current
+counter first, and use an idempotency key when the invoke surface supports it.
+
+## Event store
+
+Read operations include `list`, `list-by-aggregate`, and `list-by-type`.
+Publishing persists a domain event:
+
+```bash
+aops agent schema --tool sys.event-store.publish --summary --json
+aops agent invoke --tool sys.event-store.publish \
+  --input '@event.json' --preview --json
+aops agent invoke --tool sys.event-store.publish \
+  --input '@event.json' --apply --idempotency-key event-001 --json
+```
+
+Use the business domain as the semantic owner. Sys stores the event; it does
+not invent aggregate or event-type conventions for another domain. Preview
+cleanup and verify retention scope before applying it.
+
+## Rate limiter
+
+```bash
+aops agent invoke --tool sys.rate-limiter.check \
+  --input '{"body":{"key":"user:123","scope":"login"}}' --json
+aops agent invoke --tool sys.rate-limiter.record-attempt \
+  --input '@rate-attempt.json' --preview --json
+```
+
+`record-attempt`, `reset`, and `cleanup-expired` mutate database state. Inspect
+the live contract and current stats before reset/cleanup. Do not put secrets or
+raw authentication tokens into limiter keys.
+
+## Safety and troubleshooting
+
+1. Use `aops agent tools --domain sys --summary --json` to confirm the connected
+   server actually exposes the operation.
+2. Use `aops agent schema --tool sys.<operation> --summary --json` before every
+   new raw payload.
+3. Stop random retries after a validation error; compare against full schema or
+   the operation detail.
+4. Keep tenant/scope context explicit when the server requires it.
+5. Preview writes when supported, apply once, then read back the result.