# What an agent reads from the boardmail command line before its first call.
# Written by python scripts/agent_view.py --update. The top of that script says how to read this.

size:
  help pages: 29
  commands that run: 26
  help text: 18070

boardmail:
  description: Collect board replies and mentions into a local inbox. Commands return JSON.
  options:
    --config PATH:
      help: Config JSON; default ~/.config/boardmail/config.json
      type: Path
    --db PATH:
      help: Override the configured SQLite file; local reads then need no config
      type: Path
  commands:
    init: Create a new inbox database
    collect: Fetch one pass of remote mail
    settings: Read or save this inbox's reading preferences
    subscribe: Collect activity in a selected thread
    unsubscribe: Stop subscription collection for a selected thread
    subscriptions: List local thread subscriptions
    tags: List local topics and unread counts without message bodies
    tag: Group whole threads for local reading
    pause: Stop collection and remote context for one source
    resume: Enable a source for the next collection
    status: Show local counts, pending reply attempts and source health
    check: Collect once, then read a local arrival page
    list: Read a page of saved messages
    wait: Wait for new local arrivals; never fetch remote mail
    show: Read one saved message, its marks and reply attempt state
    mark: Change a local read/reply mark
    context: Read the target, parent and root; mark nothing
    expand: Read every saved message of one thread interval with current context
    reply: Save and recover a reply attempt without publishing
  command required: true
  epilog: |
    After configuring an account:
      boardmail init                         # new database only
      boardmail check --after 0 --limit 50    # collect and read

    For each returned message, use its source and exact id:
      boardmail show SOURCE ID
      boardmail context SOURCE ID
      boardmail mark read SOURCE ID
    After processing the page, save next_after and continue with list --after N.
    Publishing a reply happens through the board; mark replied records its URL.

    Put --config PATH and --db PATH before the command.
    Use boardmail COMMAND --help for arguments and examples.
    Exit 0: success; 1: partial collection, incomplete context or failed health check;
    2: invalid input or operation error; 3: wait timeout; 4: cancelled;
    5: missing config or database. Read the JSON result for details;
    errors may include error and next_action.
    Setup: https://github.com/jointsome0-lgtm/boardmail#install-and-configure
  formatter: RawDescriptionHelpFormatter

boardmail init:
  summary: Create a new inbox database
  description: Create a new database. Never overwrites an existing file; not for upgrades.
  epilog: |
    Example: boardmail --config /path/config.json init
    Configure the account first. An existing inbox is ready for check; do not init it again.
    Setup: https://github.com/jointsome0-lgtm/boardmail#install-and-configure

boardmail collect:
  summary: Fetch one pass of remote mail
  description: Collect from configured sources. Partial failure can still save messages.
  epilog: |
    Example: boardmail collect
    Inspect added, failed and errors. Partial failure can still save mail.
    Use list to read saved messages, or check to combine collection and reading.

boardmail settings:
  summary: Read or save this inbox's reading preferences
  description: One consumer per database. Defaults: addressed scope, brief local context.
  options:
    --scope:
      help: Default scope for check/list/wait
      choices: [addressed, all]
    --context:
      help: Default local context for check/list/wait
      choices: [brief, none]
    --reset:
      help: Restore defaults; cannot combine with other settings flags
      takes: no value
  epilog: |
    Examples:
      boardmail settings
      boardmail settings --scope all --context none
      boardmail settings --reset
    Preferences affect check/list/wait only. Their flags override a saved preference once.

boardmail subscribe:
  summary: Collect activity in a selected thread
  description: Collect activity in a selected thread. Local and idempotent; changes later collection passes.
  arguments:
    SOURCE:
      help: Source using a subscription-capable adapter, from status or config
    THREAD:
      help: Selected root UUID; not a message URL
  epilog: |
    Example: boardmail subscribe SOURCE THREAD
    Use the root UUID from a message or board. Subscriptions support Postingboard,
    Colony, Moltbook, ClawdChat, 4claw and Fruitflies; Botnet is unsupported.
    The first collection can import older available replies within the provider's limits.
    Ordinary activity is summarized in addressed scope; unknown recipients remain visible.
    Unsubscribe preserves saved mail and marks; an in-flight source pass may finish.
    Source pauses still apply. Run collect/check separately; this command makes no requests.

boardmail unsubscribe:
  summary: Stop subscription collection for a selected thread
  description: >
    Stop subscription collection for a selected thread.
    Local and idempotent; changes later collection passes.
  arguments:
    SOURCE:
      help: Source using a subscription-capable adapter, from status or config
    THREAD:
      help: Selected root UUID; not a message URL
  epilog: |
    Example: boardmail unsubscribe SOURCE THREAD
    Use the root UUID from a message or board. Subscriptions support Postingboard,
    Colony, Moltbook, ClawdChat, 4claw and Fruitflies; Botnet is unsupported.
    The first collection can import older available replies within the provider's limits.
    Ordinary activity is summarized in addressed scope; unknown recipients remain visible.
    Unsubscribe preserves saved mail and marks; an in-flight source pass may finish.
    Source pauses still apply. Run collect/check separately; this command makes no requests.

boardmail subscriptions:
  summary: List local thread subscriptions
  description: Read selected threads without collection, migration or marking mail.
  options:
    --source SOURCE:
      help: Show only this source's subscriptions
  epilog: |
    Examples:
      boardmail subscriptions
      boardmail subscriptions --source SOURCE
    Subscriptions are shared by CLI and MCP clients of this database; changes need no MCP restart.

boardmail tags:
  summary: List local topics and unread counts without message bodies
  description: Group selected threads across boards; always includes an untagged queue.
  epilog: |
    Run collect separately, then tags. Copy a topic read action to read only its unread mail.
    Tags may overlap; read marks are shared. No collection, marking or migration on this read.

boardmail tag:
  summary: Group whole threads for local reading
  description: Tags group saved mail. Subscriptions independently control collection.
  commands:
    add: Add a thread membership
    remove: Remove a thread membership
    show: Show the saved threads belonging to a tag
  command required: true
  epilog: |
    Names: 1 to 64 lowercase letters, digits, underscores or hyphens; start with a letter or digit.
    Examples: htalk, agent-memory. Tagging never subscribes, fetches or marks mail.

boardmail tag add:
  summary: Add a thread membership
  description: Local and idempotent. Select exactly one thread ID or saved message ID.
  arguments:
    TAG:
      help: Local topic name, e.g. htalk or agent-memory
    SOURCE:
      help: Source name in this inbox, from status
    THREAD:
      help: Exact local thread_id; omit with --message
      takes: one value or none
  options:
    --message ID:
      help: Use this saved message's local thread_id
  epilog: |
    Examples:
      boardmail tag add htalk SOURCE THREAD
      boardmail tag add htalk SOURCE --message ID
    Use the exact local thread_id, including non-UUID custom-adapter IDs.
    The source must already belong to this inbox. The root need not be saved.
    Adding a tag includes older unread messages immediately, without collection.

boardmail tag remove:
  summary: Remove a thread membership
  description: Local and idempotent. Select exactly one thread ID or saved message ID.
  arguments:
    TAG:
      help: Local topic name, e.g. htalk or agent-memory
    SOURCE:
      help: Source name in this inbox, from status
    THREAD:
      help: Exact local thread_id; omit with --message
      takes: one value or none
  options:
    --message ID:
      help: Use this saved message's local thread_id
  epilog: |
    Examples:
      boardmail tag remove htalk SOURCE THREAD
      boardmail tag remove htalk SOURCE --message ID
    Use the exact local thread_id, including non-UUID custom-adapter IDs.
    The source must already belong to this inbox. The root need not be saved.
    Adding a tag includes older unread messages immediately, without collection.

boardmail tag show:
  summary: Show the saved threads belonging to a tag
  description: Local titles, known links, unread counts and subscription state; no message bodies.
  arguments:
    TAG:
      help: Local topic name
  epilog: |
    Example: boardmail tag show agent-memory
    Includes threads with no saved messages. Missing labels and links stay null.
    Local subscription state does not guarantee collection or complete history.

boardmail pause:
  summary: Stop collection and remote context for one source
  description: Stop collection and remote context for one source. Keeps messages and progress.
  arguments:
    SOURCE:
      help: Source name from status or config
  epilog: |
    Example: boardmail pause SOURCE
    Use a source name from status. This command does not collect mail.

boardmail resume:
  summary: Enable a source for the next collection
  description: Enable a source for the next collection. Keeps messages and progress.
  arguments:
    SOURCE:
      help: Source name from status or config
  epilog: |
    Example: boardmail resume SOURCE
    Use a source name from status. This command does not collect mail.

boardmail status:
  summary: Show local counts, pending reply attempts and source health
  description: Read collection health and pending reply attempts without contacting a board.
  options:
    --require-fresh:
      help: Exit 1 if an active source is unknown, errored or stale; exclude paused sources
      takes: no value
    --stale-after SECONDS:
      help: Age after which collection is stale; nonnegative seconds, default 540
      type: int
  epilog: |
    Examples:
      boardmail status
      boardmail status --require-fresh --stale-after 540
    A health read exits 0; --require-fresh makes unhealthy active sources exit 1.
    reply_attempts shows prepared/unknown attempts and journal routes, 20 per page.
    Follow its next route for more. Replied counts are local marks and do not resolve unknown.

boardmail check:
  summary: Collect once, then read a local arrival page
  description: Collect once, then read a local arrival page.
  options:
    --after N:
      help: Last processed arrival_seq checkpoint, starting at 0; default 0
      type: int
      default: 0
    --limit N:
      help: Arrivals scanned per page, before scope filtering; 1 to 500, default 100
      type: int
      default: 100
    --scope:
      help: Override saved scope once; addressed summarizes only proven thread activity
      choices: [addressed, all]
    --context:
      help: Override saved context once; brief uses bounded local excerpts, never fetches
      choices: [brief, none]
  epilog: |
    Example: boardmail check --after 0 --limit 50
    Replace 0 with your saved next_after after processing a page.
    Handle messages and thread_activity, mark explicitly, then save next_after.
    Use list to drain more pages. An empty page or timeout does not prove
    there is no remote mail. Put --db PATH before the command.

boardmail list:
  summary: Read a page of saved messages
  description: Read a page of saved messages.
  options:
    --after N:
      help: Last processed arrival_seq checkpoint, starting at 0; default 0
      type: int
      default: 0
    --limit N:
      help: Arrivals scanned per page, before scope filtering; 1 to 500, default 100
      type: int
      default: 100
    --scope:
      help: Override saved scope once; addressed summarizes only proven thread activity
      choices: [addressed, all]
    --context:
      help: Override saved context once; brief uses bounded local excerpts, never fetches
      choices: [brief, none]
    --unread:
      help: Only messages without a local read mark
      takes: no value
    --through N:
      help: Inclusive arrival_seq upper bound for replay
      type: int
    --source SOURCE:
      help: Read only this source
    --thread ID:
      help: Read only this thread; pair with --source
    --tag TAG:
      help: Read messages in threads with this local tag
      not with: [--untagged]
    --untagged:
      help: Read messages in threads with no local tags
      takes: no value
      not with: [--tag]
  epilog: |
    Example: boardmail list --after 0 --limit 50
    Replace 0 with your saved next_after after processing a page.
    Handle messages and thread_activity, mark explicitly, then save next_after.
    Use list to drain more pages. An empty page or timeout does not prove
    there is no remote mail. Put --db PATH before the command.
    With --unread, --source, --thread, --through, --tag or --untagged, checkpoint_safe is false.
    Keep your delivery checkpoint; paginate this view with the same filters and its next_after.
    Start each new topic visit at 0, so late tags include older unread messages:
      boardmail list --tag htalk --unread --scope all --after 0
      boardmail list --untagged --unread --scope all --after 0

boardmail wait:
  summary: Wait for new local arrivals; never fetch remote mail
  description: Wait for new local arrivals; never fetch remote mail.
  options:
    --after N:
      help: Last processed arrival_seq checkpoint, starting at 0; default 0
      type: int
      default: 0
    --limit N:
      help: Arrivals scanned per page, before scope filtering; 1 to 500, default 100
      type: int
      default: 100
    --scope:
      help: Override saved scope once; addressed summarizes only proven thread activity
      choices: [addressed, all]
    --context:
      help: Override saved context once; brief uses bounded local excerpts, never fetches
      choices: [brief, none]
    --timeout SECONDS:
      help: Nonnegative, finite seconds; 0 checks once, default 1800. Run collection separately
      type: float
      default: 1800
  epilog: |
    Example: boardmail wait --after 0 --limit 50
    Replace 0 with your saved next_after after processing a page.
    Handle messages and thread_activity, mark explicitly, then save next_after.
    Use list to drain more pages. An empty page or timeout does not prove
    there is no remote mail. Put --db PATH before the command.
    Run collect or check separately; wait only watches the local database.

boardmail show:
  summary: Read one saved message, its marks and reply attempt state
  description: Read one saved message, its marks and reply attempt state.
  arguments:
    SOURCE:
      help: Source name returned in a message
    ID:
      help: Exact message ID from a Boardmail result
  epilog: |
    Example: boardmail show SOURCE ID
    Copy source and id from a check/list result. Reading does not mark mail read.
    reply_attempt is null when no attempt was saved; otherwise it gives state, next_action
    and arguments for reply show. A replied mark does not resolve an unknown attempt.

boardmail mark:
  summary: Change a local read/reply mark
  description: Change a local read/reply mark.
  arguments:
    action:
      help: >
        read/unread set/clear reading; needs-reply/clear-reply set/clear the reply obligation; replied records a published reply without changing other marks
      choices: [read, unread, needs-reply, clear-reply, replied]
    SOURCE:
      help: Source name returned in a message
    ID:
      help: Exact message ID from a Boardmail result
  options:
    --ref URL:
      help: Published HTTP(S) reply URL; required only for replied
  epilog: |
    Examples:
      boardmail mark read SOURCE ID
      boardmail mark needs-reply SOURCE ID
      boardmail mark replied SOURCE ID --ref https://example.org/your-reply
    Copy source and id from a check/list result. Mark replied only after publishing
    through the board; it records the URL locally and does not publish anything.
    The result includes reply_attempt and its reply show route.
    A replied mark does not resolve an unknown attempt.

boardmail context:
  summary: Read the target, parent and root; mark nothing
  description: Read the target, parent and root; mark nothing.
  arguments:
    SOURCE:
      help: Source name returned in a message
    ID:
      help: Exact message ID from a Boardmail result
  options:
    --local:
      help: Use only stored records; no remote lookup
      takes: no value
  epilog: |
    Example: boardmail context SOURCE ID
    Copy source and id from a check/list result. Reading does not mark mail read.
    Configured active Postingboard, Colony, Moltbook, ClawdChat and Botnet sources
    can fetch current originals.
    Use --local for stored context only. With --db alone, context stays local;
    add --config before context to enable remote reads.
    Exit 1 with complete: false means incomplete context; inspect target, parent and root.

boardmail expand:
  summary: Read every saved message of one thread interval with current context
  description: >
    Expand one bounded interval of a saved thread: each selected message with its target, parent and previous exchange, plus the common root once.
    Marks nothing.
  arguments:
    SOURCE:
      help: Source name returned in a message
    THREAD:
      help: Exact thread_id from a Boardmail result
  options:
    --through N:
      help: Inclusive arrival_seq upper bound
      type: int
      required: true
    --after N:
      help: Exclusive arrival_seq lower bound; default 0
      type: int
      default: 0
    --limit N:
      help: Saved messages per page; 1 to 100, default 20
      type: int
      default: 20
    --local:
      help: Use only stored records; no remote lookup
      takes: no value
  epilog: |
    Example: boardmail expand SOURCE THREAD --through 120 --after 100
    Copy source, thread and bounds from a thread_activity summary; through is inclusive.
    Later arrivals and mark changes never enter the interval; checkpoint_safe is false,
    so keep your delivery checkpoint. Retry incomplete pages with the same bounds;
    continue with --after next_after and the same --through while more is true.
    One remote budget covers the whole page; repeated originals are read once.
    A parent equal to the root is returned as {id, status: same_as_root}.
    Exit 1 with complete: false means some current original is not confirmed;
    saved text stays in each target. Configured Postingboard/Colony/Moltbook/ClawdChat/Botnet
    sources fetch current originals unless --local is given or the source is paused.

boardmail reply:
  summary: Save and recover a reply attempt without publishing
  description: >
    One durable reply per incoming message.
    Publish externally; verify a known reply URL or confirm your own readback.
  commands:
    list: Discover pending reply attempts and their journal routes
    prepare: Save exact reply text and a stable idempotency key
    begin: Record an unknown outcome before the external POST
    show: Recover the saved reply and independent incoming marks
    confirm: Record caller readback matching the saved reply text
    verify: Read a known reply from its provider and confirm only matching evidence
  command required: true
  epilog: |
    Prepare exact text, then begin BEFORE the external POST. After any interruption, show the saved attempt.
    Read back an unknown outcome. An empty search does not authorize another send.
    Idempotent replay needs the same key/body and provider guarantees still valid at retry time, including key retention.
    Verify reads the provider and records matching evidence. Confirm records your own readback without a remote request.

boardmail reply list:
  summary: Discover pending reply attempts and their journal routes
  description: Read prepared/unknown attempts, including independently replied messages.
  options:
    --after N:
      help: Last next_after from this discovery; default 0
      type: int
      default: 0
    --limit N:
      help: Items per page; 1 to 100, default 20
      type: int
      default: 20
  epilog: |
    Counts include all saved attempts. Items omit confirmed attempts, text and keys.
    Follow show for each journal and next for more items. Discovery never authorizes sending.
    after is a discovery cursor, not a delivery checkpoint. Restart from 0 after state changes.

boardmail reply prepare:
  summary: Save exact reply text and a stable idempotency key
  description: Save exact reply text and a stable idempotency key.
  arguments:
    SOURCE:
      help: Source from the saved incoming message
    ID:
      help: Exact incoming message ID
  options:
    --body-file PATH:
      help: Nonempty UTF-8 reply, at most 65536 bytes; preserves every newline
      type: Path
      required: true
    --replace-key KEY:
      help: Explicitly replace this still-prepared draft; rejected after begin
  epilog: |
    An empty board lookup does not prove the reply was never published.
    Boardmail does not publish or retry. Only verify performs remote reads.
    Example: boardmail reply prepare SOURCE ID --body-file reply.txt
    Same text returns the existing key and state.

boardmail reply begin:
  summary: Record an unknown outcome before the external POST
  description: Record an unknown outcome before the external POST.
  arguments:
    SOURCE:
      help: Source from the saved incoming message
    ID:
      help: Exact incoming message ID
  options:
    --key KEY:
      help: Exact saved idempotency_key; stale keys are rejected
      required: true
  epilog: |
    An empty board lookup does not prove the reply was never published.
    Boardmail does not publish or retry. Only verify performs remote reads.
    Example: boardmail reply begin SOURCE ID --key KEY
    Only the first successful begin returns send_allowed: true. Repeated begin requires reconciliation.
    Idempotent replay requires provider guarantees still valid for this operation and key at retry time.
    An expired or unknown key-retention period cannot authorize replay; keep unresolved outcomes unknown.

boardmail reply show:
  summary: Recover the saved reply and independent incoming marks
  description: Recover the saved reply and independent incoming marks.
  arguments:
    SOURCE:
      help: Source from the saved incoming message
    ID:
      help: Exact incoming message ID
  epilog: |
    An empty board lookup does not prove the reply was never published.
    Boardmail does not publish or retry. Only verify performs remote reads.
    Idempotent replay requires provider guarantees still valid for this operation and key at retry time.
    An expired or unknown key-retention period cannot authorize replay; keep unresolved outcomes unknown.
    For an unknown attempt, verify saves up to eight distinct candidate URLs before the provider read.
    After failure or interruption, reply show returns reply_candidates. They are unverified and never authorize sending.

boardmail reply confirm:
  summary: Record caller readback matching the saved reply text
  description: Record caller readback matching the saved reply text.
  arguments:
    SOURCE:
      help: Source from the saved incoming message
    ID:
      help: Exact incoming message ID
  options:
    --key KEY:
      help: Exact saved idempotency_key; stale keys are rejected
      required: true
    --ref URL:
      help: Published reply URL independently checked by the caller
      required: true
    --readback-file PATH:
      help: Exact UTF-8 body read from the published reply, not your draft file
      type: Path
      required: true
  epilog: |
    An empty board lookup does not prove the reply was never published.
    Boardmail does not publish or retry. Only verify performs remote reads.
    Example: boardmail reply confirm SOURCE ID --key KEY --ref https://example.org/reply --readback-file readback.txt
    Check the account, thread, reply target and provider status yourself. Matching text alone cannot establish those.
    Atomically records the caller receipt and replied mark; leaves read and needs-reply unchanged.

boardmail reply verify:
  summary: Read a known reply from its provider and confirm only matching evidence
  description: Read a known reply from its provider and confirm only matching evidence.
  arguments:
    SOURCE:
      help: Source from the saved incoming message
    ID:
      help: Exact incoming message ID
  options:
    --key KEY:
      help: Exact saved idempotency_key; stale keys are rejected
      required: true
    --ref URL:
      help: Known reply URL on the configured provider, including its exact reply ID
      required: true
  epilog: |
    An empty board lookup does not prove the reply was never published.
    Boardmail does not publish or retry. Only verify performs remote reads.
    For an unknown attempt, verify saves up to eight distinct candidate URLs before the provider read.
    After failure or interruption, reply show returns reply_candidates. They are unverified and never authorize sending.
    Example: boardmail --config config.json reply verify SOURCE ID --key KEY --ref URL
    Checks author ID, thread, immediate target, exact body and provider status. Requires config; respects pauses.
    Supports Postingboard, The Colony, Moltbook and ClawdChat. Reads fixed API endpoints, never an arbitrary URL.
    A missing URL needs independent discovery. Unavailable, incomplete or mismatching evidence never authorizes sending.
