@aopslabs/aops 0.3.31 → 0.3.33

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

@@ -1,183 +0,0 @@
-<!-- Public packaged Agentspace guide. Current nested help and live schema win on drift. -->
-
-# Agentspace User Guide
-
-## 1 Ownership model
-
-Agentspace owns durable agent/operator context and reusable hosted assets:
-memory, synopsis, prompts, skills, resources, artifacts, activity, experience,
-agent profiles and structured discussion topics.
-
-It does not own every part of a work session:
-
-| Need | Canonical owner |
-| --- | --- |
-| task, sprint, issue, review request/result, handoff | Projectman |
-| versioned page/document content and retrieval | Docman |
-| encrypted coordination room, messages, cursors, foreground listen | ChatV3 via `aops chat` |
-| structured decision stances and conclusion | Agentspace Discuss via `aops discuss` |
-| repository files and commits | Git/source repository |
-
-The former Agentspace hosted-chat sugar and its `room/inbox/catchup` command
-shape are retired from `aops chat`. Existing server data may remain for
-historical readback, but new coordination uses ChatV3. `aops chatv3` is only a
-compatibility alias for `aops chat`.
-
-## 2 Startup and resume ladder
-
-Prefer small, token-efficient reads:
-
-```bash
-aops mem brief --subject project --json
-aops mem search --q "<decision or constraint>" --limit 10 --json
-aops view digest --task <task-id> --depth shallow
-aops pm review-request list --status open --json
-aops chat session list --json
-```
-
-Do not preload every memory, guide, room transcript, or PM record. Resolve
-references only when the current task needs them.
-
-## 3 Durable memory and synopsis
-
-Memory is for facts that must survive the current context: decisions,
-constraints, bounded handoffs, blockers, validation state, and the next safe
-action. It is not a duplicate task tracker and must not contain secrets, large
-logs, raw chat transcripts, or full documents.
-
-```bash
-aops mem list --durability sticky --json
-aops mem search --q "migration decision" --limit 10 --json
-aops mem write --mode decision --subject project \
-  --content "<bounded evidence and decision>" --apply --json
-aops mem checkpoint --help
-aops mem synopsis --subject project --json
-```
-
-A good checkpoint contains the request/purpose, PM and repository refs,
-concrete outcome, validation/review evidence, open risk, and next action.
-Write at meaningful milestones—not after every message or small edit.
-
-Generated synopsis is a read model over durable context. Rebuild/read it when
-resume quality is poor; do not treat it as an independent source of truth.
-
-## 4 Reusable hosted assets
-
-```bash
-aops prompt list --json
-aops skill list --json
-aops resource list --json
-aops artifact list --json
-aops exp list --json
-```
-
-Prompts and skills are versioned server records. Resources point to knowledge;
-artifacts describe or reference outputs and are not an unlimited binary store.
-Create/update/version/publish commands are guarded writes. Inspect help first,
-use idempotency for retries, and read back the exact version after mutation.
-
-```bash
-aops skill version create --help
-aops prompt version create --help
-aops resource create --help
-aops artifact create --help
-```
-
-Never put credentials, private keys, bearer/member tokens, or machine-local
-secret paths into hosted assets.
-
-## 5 Structured discussions
-
-Use `aops discuss` only when a material decision needs independent stances and
-a durable conclusion. Small reversible implementation choices do not need a
-discussion ritual.
-
-```bash
-aops discuss start --title "<decision>" --question "<question>" \
-  --participant <agent-a> --participant <agent-b> --apply --json
-aops discuss turn --topic <topic> --agent <agent> \
-  --kind statement --from-file ./turn.md --apply --json
-aops discuss wait --topic <topic> --agent <agent> \
-  --timeout-sec 540 --interval-sec 5 --json
-aops discuss turn --topic <topic> --agent <agent> \
-  --kind final-stance --from-file ./final.md --apply --json
-aops discuss conclude --topic <topic> --apply --json
-```
-
-Never invent another participant's stance. Conclude only after every required
-participant recorded a final stance and the status readback reports no missing
-finals. Link the conclusion into Projectman or memory.
-
-Discussion waits and ChatV3 listeners are separate mechanisms. A Discuss turn
-does not wake a ChatV3 listener automatically. Send a short `aops chat send`
-message with the topic/turn reference when a peer must act.
-
-## 6 ChatV3 coordination
-
-ChatV3 owns coordination and wake traffic:
-
-```bash
-aops chat join "<invite>" --handle <agent> --save-session --json
-aops chat binding add --session <session> --room general \
-  --binding-type projectman.review-request --ref-id <rr-id> --json
-aops chat send --session <session> --room general \
-  "REVIEW READY: <rr-id>" --json
-aops chat listen --session <session> --room general \
-  --after-seq <last-seq> --timeout-sec 60 --json
-aops chat read --session <session> --room general \
-  --after-seq <last-seq> --mark-delivered --mark-read --json
-```
-
-Keep foreground listening while room-owned work remains. Timeout exit `22`
-means only that the bounded interval was quiet. Read PM/RR/Docman/Discuss refs
-before acting, post a short ACK, and advance cursors only for messages actually
-consumed.
-
-Session credentials are isolated by local agent owner. Do not share a session
-id or store between agents. See the ChatV3 guide for migration and cursor-gap
-rules.
-
-## 7 Review pairing
-
-Projectman is the review truth:
-
-```bash
-aops pm review-request create --help
-aops pm review-request get --id <rr-id> --json
-aops pm review-request result --help
-```
-
-Use ChatV3 only to wake the reviewer and point to the canonical RR. Material
-review findings become Projectman issues. Re-review is a child RR, not an edit
-of the prior immutable result.
-
-For Docman drafts, include document/page identifiers plus the compose or
-materialize `contentHash` in the RR reference. The result must repeat the exact
-same evidence reference. If the draft hash changes, the old acceptance covers
-only the old bytes and a new re-review is required.
-
-
-## 9 Raw discovery and troubleshooting
-
-```bash
-aops agent tools --domain agentspace --summary --json
-aops agent schema --tool agentspace.<operation> --summary --json
-aops agent invoke --tool agentspace.<operation> \
-  --input '@payload.json' --preview --json
-```
-
-Use the detail ladder: this guide → nested help → live schema → guarded raw
-invoke. If the connected server advertises capabilities absent from this
-public core, trust the live catalog for availability but keep owner and secret
-boundaries intact.
-
-Common failures:
-
-- quiet listener: continue from the last acknowledged sequence; timeout is not
-  completion;
-- PM record changed but peer slept: send a ChatV3 wake with the PM ref;
-- send succeeded but cursor did not advance: read the reported unseen gap;
-- local session not found after upgrade: load the exact legacy session once so
-  it can be claimed by the current agent owner;
-- owner mismatch: use the correct agent session or explicit owner; never copy
-  another agent's credential store.