For a step-by-step workflow, read Leave a note or comment, then review delivery, or for the surface-choice overview, read which one to use. For current provider support, consult Capabilities; this chapter describes reviewed surfaces and their limits.
Notes and comments
Notes preserve project knowledge; Local Comments attach discussion to a durable project, Campaign or Mission identity. The built-in comment destination is Local-only; saved project/global defaults can differ. Inspect that choice and the exact binding before assuming any content is shared. Native Notes have revision history; the current Notes pane and command use the separate timestamped scratchpad described below.
Boundary and recovery: GitHub is not synonymous with all notes. Adapter plans and read-only previews are not proof of writable multi-user sync; private repositories require authenticated permissions.
Inspect the configured comment destination
Replace PROJECT with the exact registered name. Inspect the project's destination before assuming a message is shared externally.
Inspection with conditional local recovery writes.
commandem comment destination PROJECT --json
commandem comment thread PROJECT --jsonExpected result: The effective destination plan and local project thread. These queries do not author comments or publish externally. If a native thread or destination store is invalid, the reader can move it to a preserved quarantine copy and report recovery. A local comment's existence does not prove tracker delivery or multi-user sync.
Leave a native local Mission comment
Replace PROJECT and MISSION_ID with a real project and its durable Mission ID from Roadmap, for example an actual m-xxxxxxxx value. Do not use a positional Mission number.
Writes local state.
commandem comment thread PROJECT --mission-id MISSION_ID \
--add "Please review the acceptance criteria." --jsonExpected result: A comment attached to that local Mission thread. This command does not open a GitHub issue, publish to a tracker or start an agent; review the separate sync adapter before claiming external delivery.
- Choose scope
Attach discussion to the intended project, Campaign or Mission.
- Inspect destination
Distinguish local storage, tracker delivery and live operator routing.
- Check evidence
Inspect thread or delivery evidence; do not equate a queued message with receipt.
Private scratchpad append
commandem notes PROJECT "note text" explicitly appends a timestamped line to the project's local scratchpad. A successful append creates an owner-only file or tightens an existing regular file to mode 0600, without rewriting its earlier notes. Merely showing or listing Notes does not change a legacy file's permissions.
This owner/alias-checked append is implemented for Unix platforms. The Windows prototype explicitly refuses scratchpad append because the equivalent owner and alias validation is not implemented there; a Windows build is not Notes parity.
The append path checks the opened directory and file identities. It refuses a linked Notes directory, a symbolic link or multiply linked file, a nonregular target, a file owned by another user, or a Notes directory writable by a group or everyone. These checks protect the explicit local append; they are not encryption, multi-user access control or a sandbox against another process with your filesystem authority.
Append a private project decision
Replace PROJECT with the exact registered name and choose nonsensitive note text. The first command writes; the second reads the saved scratchpad.
Writes local state, then reads it.
commandem notes PROJECT "Decision: review the local test result before landing."
commandem notes PROJECT --jsonExpected result: A successful append acknowledgement and the project's timestamped notes as JSON. The append makes the accepted file owner-only and preserves preceding note bytes. It does not publish a comment, synchronize a destination or contact a provider. Do not store credentials in Notes.
Boundary and recovery: If append is refused, inspect the reported ownership, file type or alias before retrying. Preserve existing content and resolve the intended local file deliberately; do not bypass the refusal by deleting a linked target or loosening permissions. A failed append can already have created the private directory or tightened an accepted file's mode. --clear deletes the project's scratchpad; it is not a repair or undo operation. See the CLI example and recovery notes.
Board messages and notifications
Board read state feeds Home and Notifications. Marking board messages read preserves their history. A notification badge should reflect the same underlying unread state, not an independent dismissal ledger.
commandem board PROJECT --history --json reads retained Board, Announce and governed-bus metadata without changing read state. Use --source, --outcome or --lane for exact filters. Standard mode can explicitly include bounded local Board excerpts; Strict suppresses bodies and Incognito suppresses history reads. Explicit tell --reply-to references link retained replies; --acknowledge records a reciprocal peer claim, not authenticated execution.
Boundary and recovery: A clear control should not erase history or repair a fault. If Home, the icon and the feed disagree, retain counts/timestamps and use notification troubleshooting.
Inspect board history without marking it read
Replace PROJECT with the exact registered name. History is explicitly read-only; strict privacy omits message bodies and --n bounds the result.
Read-only inspection.
commandem board PROJECT --history --source board \
--history-privacy strict --json --n 20Expected result: Bounded board-source history and coverage metadata. The unread count does not change; omitted bodies or unavailable source evidence are reported rather than treated as empty history.
Notification preferences control delivery and priority. Home Messages follows the same underlying board read state.
Sync adapters and project-management bridges
Inspect configured collaboration connections, scope mapping, authentication and conflict handling before synchronizing content. External project-management records can map to Campaign/Mission work, but the mapping must be explicit.
Boundary and recovery: An available connection is not feature parity with Jira, Notion or every provider. Distinguish implementation, read-only discovery, planned write support and unsupported operations.
Standalone Local Markdown setup
This configuration path saves only an existing directory binding and its empty checkpoint. CLI flags landed in source d43539b0; check commandem sync --help for both setup flags in the binary you use. Source acceptance did not update the installed CLI or certify desktop Add/Edit or web/mobile setup.
| Field | Meaning and limit |
|---|---|
| Binding and project | Exact logical identity supplied by the request; setup does not resolve registry membership. Different occupied binding IDs cannot be replaced. |
| Account and Profile | Recorded references, not proof of sign-in, a credential or access. Setup makes no provider request. |
| Directory | Canonical real directory, mode directory; state and lock must remain outside it. Inspection does not verify write permission, audience or replication. |
| Direction and authority | push and local_primary: push enabled, pull disabled, local content authoritative. Configuration starts neither delivery nor import. |
| Privacy | Acknowledged Standard or Strict configuration; Incognito refuses persistence. Future content has a separate exact operation and privacy review. |
| Retention | local_filesystem: later current Markdown and tombstones, not immutable external history. Cloud replication, collaborator ACLs and Obsidian Sync are not certified. |
Preview metadata, then save the exact approved binding
Prepare request.json using the configuration request example. Use an existing real directory and store request/review files privately outside it. Requires jq and a CLI whose help includes both setup flags.
Preview inspects; extraction saves local review files; apply writes configuration only.
umask 077
commandem sync collaboration --preview-local-markdown-setup request.json --json > preview.json
jq -e '.local_markdown_setup_plan | select(.allowed == true)' preview.json > plan.jsonStop if preview or extraction fails. Read the complete binding, disclosures, denials, retention and digest before continuing. A successful preview can still be blocked with allowed: false. Apply accepts the extracted plan rather than the response wrapper:
commandem sync collaboration --apply-local-markdown-setup plan.json \
--approve-digest "$(jq -r '.digest' plan.json)" --jsonExpected result: local_markdown_setup.created: true records a new push-only binding and empty checkpoint. An exact replay returns created: false with unchanged saved bytes and timestamps. No content is queued, exported or imported, no destination files are created, no watcher starts and comment defaults remain unchanged. This result is configuration evidence, not a delivery receipt.
Boundary and recovery: Missing/changed digest, a substituted plan, an occupied identity or incompatible/corrupt saved state refuses. Correct the request and preview again; setup cannot edit/delete bindings or migrate/quarantine state. Apply may create the ordinary support parent/lock even when a later refusal occurs. Inputs accept - for stdin; use only one setup operation, target collaboration, no project positional argument and no --dry-run on apply.
The existing --apply-local-markdown exports content and saves a two-way binding; its distinct approval is not a configuration shortcut. Read external delivery review before using any content write. A folder can be replicated by unrelated software; adapter conformance does not prove live private-provider or physical-device acceptance.
Unused destination configuration removal
Standalone removal affects only one saved collaboration configuration and its pristine empty checkpoint. Native Notes/Comments, destination files, provider objects, credentials, retained history and other saved records remain unchanged. Saved comment-default preferences are not rewritten; review any reference to the removed binding. It does not open a destination, contact a provider, authenticate an account or authorize outbound content. Preview reads the retained operations file locally for validation/proof; its bodies never enter the plan.
Source note: removal CLI and store behavior are additionally reviewed at 881843f0; the previous handbook baseline was 11249a60; the current source review is shown above. Check both removal flags in your installed CLI's commandem sync --help. This source review is not installed, desktop/mobile or live-provider certification.
| Proof | Role |
|---|---|
request.contract_digest | The actual stored contract proof for the exact binding_id, captured from a unique catalog record. Do not derive it from the displayed settings. |
state_digest | Proof of exact operations-file bytes captured by preview. Any later file change, including unrelated formatting/state, invalidates the review. |
digest | The complete removal plan approval passed to --approve-digest. It is distinct from the two proofs above. |
Review before removing an unused setup
Follow the exact request, stdin and approval examples. Requires jq and a binary exposing --preview-binding-removal and --apply-binding-removal. Each capture uses a fresh private directory outside the destination; stop if directory creation or entry fails, and keep later snippets there. Retain its review files privately; no automatic cleanup is performed.
Preview reads; review files are saved locally; only explicit apply removes configuration.
- Capture one exact saved binding and its
contract_digestinto the schema-1 request; stop on duplicate, missing or invalid proof. - Preview the request, then extract
binding_removal_planonly when allowed. Read its captured identity, checkpoint, denials and disclosures. - Make a separate approval decision before applying that exact plan and its
digest. Verifybinding_removal.removed: true, the exact binding ID and matchingreview_digest.
Expected result: the matching configuration-removal result, with no destination/provider/native content deletion. Apply rechecks the full plan under the ordinary local lock before one atomic store replacement. Preview creates no state, lock, migration or quarantine; a later apply refusal may create its usual lock file.
Refusal and uncertainty: pending and terminal reviews, outbound operations, inbound events, receipts, conflicts, tombstones, drafts, merges and Note conflicts prevent removal. A touched blank checkpoint is not unused evidence. Corrupt/unsupported state, changed proof or ambiguous filesystem artifacts refuse; do not clear history, remove files or weaken checks to proceed. A replay refuses.
An interrupted attempt or absent/mismatched result is unconfirmed. Preserve its review, inspect a fresh catalog and obtain a new preview if the binding remains; do not blindly repeat the old approval. Used-binding deactivation/recovery and mobile removal and live-provider acceptance remain separate boundaries. The desktop review route is described under Saved destinations.
Read-only Git workspace prerequisite
This standalone inspection is accepted CLI source at 80134145, not an installed-binary update or Git synchronization capability. The previous handbook-wide review was 11249a60; the current source review is shown above. Confirm --inspect-git-workspace in the intended binary's commandem sync --help; no live-provider authentication, remote permissions or publication posture is certified.
| Field | Meaning and limit |
|---|---|
schema_version | Required integer 1; unsupported schemas refuse. |
repository | Required string selecting an existing checkout's canonical absolute root. Subdirectories and symbolic-link aliases are not equivalent selections. |
branch | Required string naming the exact currently checked-out local branch, not HEAD, a refs/ path or a revision expression. A committed HEAD is required. |
namespace | Required string selecting a portable relative directory without traversal or Git metadata. A missing namespace can pass and remains absent; inspection creates nothing there. |
Inspect without starting Git synchronization
Prepare the exact request using the schema-1 selection example. Keep it private outside the checkout. The file and stdin forms inspect the same request:
Read-only local prerequisite inspection.
commandem sync collaboration --inspect-git-workspace git-workspace-request.json --json
commandem sync collaboration --inspect-git-workspace - --json < git-workspace-request.jsonExpected result: a schema-1 action: preview response with collaboration_sync: null and git_workspace. Exit 0 includes blocked reports; inspect state, reason, local_prerequisite, linked_worktree, namespace_exists and all limitations. A healthy report means only local_prerequisite_only; authentication stays unknown and synchronization stays unsupported. It is not an approval or delivery receipt.
Boundary and recovery: No Apply, fetch, pull, push, checkout, staging, commit, configuration save or namespace mutation is available here. Unrelated dirty files are allowed; dirty, untracked and ignored managed files refuse. Remote existence, private authentication, permissions and publication posture remain unknown; pull-before-push, conflicts, provenance, revisions and delivery remain unimplemented. Evidence is point-in-time, so reinspect after concurrent changes rather than treating a previous result as continuing authority.
The inspector may read and hash managed contents locally, but its report omits input paths/refs, remote URLs, object IDs, filenames, bodies and raw Git diagnostics. Inputs are one strict JSON object, at most 2 MiB and 64 nested levels, with no duplicate or unknown fields, trailing values, invalid UTF-8 or malformed Unicode escapes. Missing/null required strings refuse; empty strings reach the core's blocked-selection rules. Use only the standalone flag, --json and optional --dry-run, target collaboration and no project positional argument. Fixed malformed-input or infrastructure diagnostics are not successful prerequisite evidence.
The no-write boundary covers the standalone inspection, not unchanged CLI startup settings/dotenv reads, logging or abandoned-session recovery. See the inspection workflow and complete limitations. Do not make a repository public or weaken permissions to bypass a refusal.
Read retained recovery evidence
From Comments → Adapters, open Recovery inbox to inspect retained retries and conflicts, their trigger/evidence/mechanism and local/remote revisions. Missing evidence stays unknown. A failed load offers Retry loading; it is not a successful empty inbox. Reading the inbox starts no repair or delivery. A later retry preview and approval are separate operations.
commandem sync collaboration --inspect-recovery-inbox --jsonThe standalone CLI inspection reads saved local state without provider access or state migration. In the adapter panel, Saved local status describes local queue/inbox/conflict records. Provider availability, credentials and ACLs remain unknown, including when the recorded state looks healthy. Refreshing this panel is not a live health probe.
Inspect Saved destinations
Add destination opens the desktop Local Markdown configuration review. Select an existing real folder and review the project, account/Profile references and disclosure before explicitly saving; this configures a destination without exporting content or starting a watcher. From a captured destination inspection, Review removal of unused destination opens a separate preview. Removal requires the exact stored contract proof and refuses recorded activity. A successful result removes only unused configuration and its empty checkpoint. Refresh afterward to inspect current metadata.
In a project's Comments, select Adapters to open Collaboration adapters, then find Saved destinations. This is a bounded inventory of current saved binding metadata, not a delivery ledger or a connection-health check. Select the leading › heading to open an inspection captured from that catalog value.
Read one destination without starting sync
Use a project whose collaboration catalog has a saved entry. An empty catalog means no entries were recorded there, not that every provider was queried.
Read-only inspection of the captured catalog.
- Open the project's Comments, then select Adapters.
- Under Saved destinations, select an entry's › heading.
- Read the identity interpretation, current account/Profile and container, then close the sheet.
Expected result: A captured settings sheet with recorded metadata or explicit unknown values. Inspecting it does not save configuration, request credentials, start sync, contact a provider or open a remote link. If the catalog refreshes while the sheet is open, the selected inspection stays unchanged; close and select again to inspect a newer value.
- Identity: An empty or duplicate recorded ID is unknown or ambiguous. Project, provider, account, Profile and container are withheld rather than guessed. Duplicate checks include entries beyond the visible prefix.
- Credentials: A configured reference does not prove a secret is available, authentication succeeded or access was granted. An explicitly unconfigured reference is different from missing or malformed credential evidence.
- Audience and retention: Both remain unknown in this catalog. Current settings do not establish who received earlier content or which account executed a historical run.
- Display limits: Up to 80 entries and 24 KiB of native document text are displayed, with individually bounded fields. A bound notice means some metadata may be omitted or clipped; it is not successful empty data.
Boundary and recovery: Preserve an unknown or ambiguous record for investigation; do not select another destination by similar wording. The inspection does not repair bindings, certify provider support or authorize delivery. For authored work, review the separate Task preview before any later sync action.
Recipes and Marketplace
Recipes are reusable prompt/workflow templates; the Marketplace groups recipes, plugins and skills. Bundled catalogs load locally first; remote refresh has a separate unavailable state.
Boundary and recovery: A catalog listing is not a security review. Confirm source and scope before running a template; remote failure must not be shown as successful emptiness.
Plugins, skills and MCP tools
Plugins extend commands; skills supply scoped agent instructions; MCP servers expose tools. Install through the supported manager and inspect declared capabilities, provenance and update evidence.
Boundary and recovery: Installation is not authorization to every tool. Managed sandboxing differs from dropping an executable in a directory; never claim universal safe isolation or auto-update coverage.
Governed agent-to-agent communication
Advisories and read-only questions use a governed bus with an audit trail. Announce routes operator messages to active chats; source and destination identity are essential for coordination.
Boundary and recovery: An external message is untrusted evidence, not owner authority. Do not let a remote advisory bypass approvals, visibility rules or execution gates.
For live operator communication, inspect Broadcast and Announce. For precise command scope, read the governed A2A command and Announce separately.