Workflow guide

Choose an audience before saving a comment

Keep Notes, Local Comments, Board Messages and external delivery distinct.

Pre-release. Reviewed October 23, 2026. This review covers code behavior, not a packaged release or provider certification.

The standalone setup section additionally reviews CLI source d43539b0. The previous handbook-wide source was 11249a60; the current review is shown above and requires its freshness gate before release.

Choose the right surface

Private Note

A local scratchpad. It is not a shared provider document.

Local Comment

A Project, Campaign or Mission discussion with a durable target.

External destination

A separately reviewed delivery with its own audience and permissions.

A Board Message addresses another project. Work in Chat starts an agent turn and can send context to the chosen provider; the other local surfaces do not. A local save is not proof that a remote service accepted your text. For a full comparison of all five surfaces (including their exact app labels and icons), read which one to use; this page covers the local-save and delivery mechanics in depth.

Save a local discussion

The built-in destination is Local-only. Inspect the effective choice because saved project/global defaults can differ. A binding or provider sign-in alone does not opt a Note or Comment into synchronization.

  1. Open Comments for the project, Campaign or Mission. Confirm the durable target and selected destination; saved defaults can change it.
  2. Write and save. Inspect the author/time and reply context. Deleted or unloaded parent comments are not interchangeable.
  3. If loading fails, use Refresh/Retry while preserving your draft. An unavailable thread is not an empty discussion.
commandem comment destination PROJECT --json
commandem comment thread PROJECT --json
commandem comment thread PROJECT --mission-id m-xxxxxxxx \
  --add "Please review the acceptance criteria."

Replace the placeholder with the actual durable Mission ID. The add example writes discussion state; inspect the destination before invoking it.

Configure a Markdown destination without exporting content

The standalone CLI setup path records an existing directory, a push-only binding and an empty checkpoint. It leaves the comment destination default unchanged. The existing --apply-local-markdown is a content export that saves a two-way binding; use its separate content review only when you intend that effect.

Build boundary: The setup flags are accepted CLI source from d43539b0. Source acceptance did not update the installed CLI or certify desktop Add/Edit, web/mobile setup or a live provider. Run commandem version and commandem sync --help; continue only if both setup flags appear in the binary you intend to use.

Prepare the request

Save this as request.json in a private working directory outside the destination. Replace the directory with an existing absolute real directory and choose deliberate logical identities. The selected directory must not itself be a symbolic link; Commandem state and its lock must stay outside its subtree.

{
  "schema_version": 1,
  "binding_id": "demo-markdown",
  "account": "local-folder",
  "profile": "work",
  "project_id": "demo",
  "directory": "/absolute/path/to/existing-directory",
  "privacy_mode": "standard",
  "acknowledged": true
}

Account, Profile and project are metadata references, not authentication, credential access or registry lookup proof. Standard and Strict permit acknowledged setup; Incognito refuses persistence. The plan fixes direction: push, authority: local_primary and file_mode: directory. Setup imports nothing and starts neither push nor pull.

Preview, inspect and extract

With jq installed, these commands use a private file-creation mask for new review artifacts. Preview itself writes no support state or destination files; shell redirection saves the requested artifact locally.

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.json

Read the exact binding, allowed, denials, disclosures, retention and digest in preview.json. A blocked preview can exit successfully with allowed: false. If preview or extraction fails, stop here. Apply accepts only the extracted local_markdown_setup_plan, not the enclosing response.

retention: local_filesystem describes later current Markdown and tombstones, not immutable external history. Directory inspection does not prove write permission, collaborator ACLs or cloud/filesystem replication. Review artifacts expose destination and account/Profile metadata; keep them private.

Approve configuration and recognize replay

After reviewing the complete plan, run the separate apply command to approve that exact digest:

commandem sync collaboration --apply-local-markdown-setup plan.json \
  --approve-digest "$(jq -r '.digest' plan.json)" --json

Expected result: local_markdown_setup.created: true for a new binding. Repeating that exact apply returns created: false and preserves saved bytes and timestamps. Neither result means content was delivered; setup saves no Note or Comment, outbox operation, review or receipt and creates no destination files. Apply may create its ordinary support parent and lock.

Missing or changed approval, modified plans and differently occupied binding IDs refuse. Correct the request and preview again; do not edit the approved plan or delete existing state to retry. Setup supplies no replacement/deletion or implicit schema recovery. Both inputs support - for stdin. Use one setup operation, target collaboration, no project positional argument and no --dry-run on apply. Future content writes need their own operation and privacy approval.

Read the destination field reference and recovery limits before a later content write.

Remove an unused saved destination

This removes saved collaboration configuration and its pristine empty checkpoint, not a Note, Comment or delivery. Native content, destination files, provider objects, credentials, retained history and other saved records remain unchanged. Saved comment-default preferences are not rewritten; review any default that referenced the removed binding. No provider is contacted. A used destination needs a separate recovery workflow; this is not a way to erase its evidence.

Source note: this CLI workflow is reviewed at 881843f0. The previous handbook baseline was 11249a60; the current source review is shown above. Source acceptance did not update the installed CLI or certify desktop/mobile removal; check that your binary's commandem sync --help exposes both removal flags before using it.

Capture one exact saved identity

Use jq and keep these review files private: they contain account, Profile, destination and configuration references. Replace the placeholder with the exact saved binding ID you intend to remove. These first steps only capture metadata and prepare a request; they do not remove anything.

umask 077
BINDING_ID='paste exact saved binding ID'
REMOVAL_REVIEW_DIR=$(mktemp -d "${TMPDIR:-/tmp}/commandem-removal.XXXXXX") &&
  cd "$REMOVAL_REVIEW_DIR" &&
  commandem sync collaboration --json > removal-catalog.json

Stop if this block fails. Use a temporary location outside the destination. Each capture creates a fresh private review directory, so fixed filenames do not overwrite an earlier review; umask 077 protects newly created files, not existing ones. Run the remaining snippets in that directory. Retain its files privately for review and any unconfirmed-result investigation; these commands do not automatically clean them up.

jq -e --arg id "$BINDING_ID" '
  [.collaboration_sync.bindings[] | select(.binding.id == $id)] as $matches
  | if ($matches | length) != 1 then error("Need one exact saved binding")
    elif ($matches[0].contract_digest | type) != "string" then error("Stored proof unavailable")
    elif ($matches[0].contract_digest | test("^sha256:[0-9a-f]{64}$") | not) then error("Stored proof invalid")
    else {schema_version: 1, binding_id: $matches[0].binding.id,
          contract_digest: $matches[0].contract_digest} end
' removal-catalog.json > removal-request.json

Stop if either command fails. A missing proof, an unknown identity or duplicate exact matches is unavailable evidence; do not choose a similarly named record, hash the displayed metadata or invent contract_digest.

Preview and review the captured configuration

commandem sync collaboration --preview-binding-removal - --json \
  < removal-request.json > removal-preview.json
jq -e '
  select(.schema_version == 1 and .action == "preview")
  | .binding_removal_plan
  | select(.schema_version == 1 and .allowed == true and (.denials | length) == 0)
' removal-preview.json > removal-plan.json

Stop on command failure or allowed: false. Read the complete plan before making an approval decision: exact binding/project, account/Profile, destination, direction/authority, checkpoint, disclosures, denials and digest. Preview reads the retained operations file locally for proof and validation; its bodies never enter the output. It creates no store, lock, migration or quarantine and opens no destination or separate native content store. Only shell redirection/extraction saves the local review files.

Pending and terminal reviews, outbound operations, inbound events, receipts, conflicts, tombstones, drafts, merges and Note conflicts all block removal. Blank cursors alone are insufficient: a touched checkpoint, deadline or timestamp change can also block it. Any operations-file change, even unrelated bytes, invalidates this review's state_digest. Preserve refused state; never clear records or edit the plan to force eligibility.

Apply only after a separate human approval decision

The next command writes saved configuration. Run it only if you have read and approved this exact allowed plan. The approval is the plan's digest, not request.contract_digest or state_digest. Do not paste the preview response wrapper into apply.

REMOVAL_DIGEST=$(jq -er '.digest | select(test("^sha256:[0-9a-f]{64}$"))' removal-plan.json)

Stop if digest extraction fails. Then, and only after that explicit approval decision:

commandem sync collaboration --apply-binding-removal - \
  --approve-digest "$REMOVAL_DIGEST" --json \
  < removal-plan.json > removal-result.json
jq -e --slurpfile plan removal-plan.json '
  .schema_version == 1 and .action == "apply"
  and .binding_removal.schema_version == 1
  and .binding_removal.removed == true
  and .binding_removal.binding_id == $plan[0].request.binding_id
  and .binding_removal.review_digest == $plan[0].digest
' removal-result.json

Expected result: a schema-1 binding_removal result with removed: true, the exact binding_id and matching review_digest. This confirms configuration removal, not content deletion, provider authentication or delivery. Apply validates the whole review again under the ordinary local lock before one atomic store replacement; a later refusal may have created that lock file. A replay refuses rather than reporting another successful removal.

A failed command, interrupted attempt, unreadable output or mismatched result is unconfirmed, not success. Preserve the review and inspect a fresh catalog; do not reuse the old approval or blindly repeat apply. If the binding remains, prepare and review a new plan. Corrupt, old/future-schema or ambiguous saved artifacts are refusal conditions, not permission to delete files. Use exactly one removal operation with target collaboration, no project positional argument, no unrelated sync flags and no --dry-run on apply. File inputs can replace -; apply still needs the extracted plan, not its wrapper.

See removal proof roles and refusal limits. This action neither opts content into sync nor broadens its audience; later content delivery still requires its separate review.

Inspect a local Git workspace prerequisite

The standalone inspector reads an existing local checkout. It does not configure or enable a Git synchronization adapter, authenticate an account or authorize a content write.

Source note: this CLI boundary is accepted at 80134145; the previous handbook baseline was 11249a60; the current source review is shown above. Source acceptance did not update the installed CLI or certify a live provider. Check commandem version and confirm --inspect-git-workspace in your binary's commandem sync --help before using it.

Select the exact checkout, branch and namespace

Save this schema-1 request as git-workspace-request.json privately outside the checkout. Replace the repository placeholder with the existing checkout's canonical absolute root, not a subdirectory or symbolic-link alias. Replace main with its exact currently checked-out local branch name, not HEAD or a revision expression. Choose a portable relative directory namespace without traversal or Git metadata; Commandem is an example, not an inferred default.

{
  "schema_version": 1,
  "repository": "/absolute/canonical/path/to/existing-checkout",
  "branch": "main",
  "namespace": "Commandem"
}

Inspect the request from a file, or use the equivalent stdin form:

commandem sync collaboration --inspect-git-workspace git-workspace-request.json --json
commandem sync collaboration --inspect-git-workspace - --json < git-workspace-request.json

Expected result: a schema-1 response with action: preview, collaboration_sync: null and a git_workspace report. Exit 0 can still mean state: blocked; read reason, local_prerequisite and every limitation. A healthy local prerequisite reports state: inspected and reason: local_prerequisite_only, while authentication: unknown and synchronization: unsupported remain unchanged. A missing namespace is not created.

  • This is local prerequisite inspection only; no Git synchronization adapter is enabled.
  • Remote existence, private authentication, permissions and publication posture remain unknown.
  • Pull-before-push, conflicts, commit provenance, revisions and delivery are not implemented.
  • Unrelated dirty files are allowed; dirty, untracked and ignored managed files are refused.
  • Evidence is point-in-time only; concurrent changes require reinspection before any future operation.

There is no Apply step. The inspection does not fetch, pull, push, check out, stage, commit, save configuration or mutate the requested namespace. Git may read and hash managed file contents locally; the report omits paths, refs, remote URLs, object IDs, filenames, bodies and raw Git diagnostics. A successful prerequisite is not proof of write permission or external delivery.

Use target collaboration, no project positional argument and no unrelated sync flags. --json and --dry-run are accepted; dry-run does not add an apply capability. Malformed input or infrastructure failure is not a blocked prerequisite report: stop and inspect the fixed diagnostic. The standalone no-write boundary does not cover unchanged CLI startup settings/dotenv reads, logging or abandoned-session recovery. See the request fields and inspection boundary.

Review external delivery

For an existing top-level local comment, choose Review saved delivery to capture its displayed revision and inspect an exact saved push-only Local Markdown destination. A preview alone sends nothing. Changing the source, destination or review requires a new preview; delivery applies the reviewed snapshot and records its own result.

  1. Choose an available adapter explicitly. Inspect audience, binding, permissions, exact payload and capability limits.
  2. Approve only the current review. Local save, queued and delivered remain different states.
  3. Inspect Sync Activity or commandem sync collaboration --json for the operation's receipt.
  4. For an eligible failed Local Markdown or configured Obsidian-folder delivery, reopen its original reviewed retry. Rebuild stale review instead of posting a duplicate comment.

Inspect messaging history

Use the read-only history view to compare retained Board, Announce and governed-bus records without starting an agent or changing unread state.

commandem board PROJECT --history --json --n 20
commandem board PROJECT --history --source board --history-privacy strict --json

Metadata is the default. --include-bodies requests bounded local Board excerpts in Standard mode; Strict suppresses bodies and Incognito suppresses the history read. --lane filters an exact sender, recipient or provider; --outcome filters the recorded outcome. Retention is bounded. App delivery is not proof that a provider consumed the message or completed work.

When posting a reply, tell --reply-to MESSAGE_ID links the retained Board message explicitly. --acknowledge requires that reference and records a reciprocal peer acknowledgement, not independently authenticated success.

Expected result and recovery

Your local text survives with the correct target. Remote delivery is claimed only with its receipt. Inspect conflicting Note versions before choosing an explicit resolution. Never make a repository public or broaden its audience to bypass missing access.

Local Markdown is a network-free reference adapter; unrelated software can replicate a selected folder. Obsidian inspection/export is not Obsidian Sync or editor certification. The desktop Add and unused-removal review routes are described under Saved destinations; destination editing and web/mobile parity remain separate acceptance boundaries. Adapter conformance is not live private-provider certification. See capability limits and privacy boundaries.