manigent-server 0.1.0__py3-none-any.whl

manigent/_catalog/skills/gmail/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: gmail
+description: >
+  Read, search, send, and archive Gmail messages. Invoked via Bash subcommands
+  (`manigent gmail search|get|labels|attachment|send|archive|auth|revoke`); the
+  token resolves from `$MANIGENT_AGENT_DIR/skill-hub/state/gmail/`. For
+  requests like "any emails about X?" or "send Y to Z" shell the matching
+  subcommand. Requires Google OAuth — install + Authenticate via Agent
+  Settings → Skills → gmail before first use.
+---
+
+# /manigent:gmail
+
+Gmail integration. The agent profile decides *when* to read/search/send;
+this skill is *how* — Bash invocations of the `manigent gmail` CLI.
+
+## Step 0 — Preflight
+
+Token at `$MANIGENT_AGENT_DIR/skill-hub/state/gmail/token.json` is required.
+If absent, reply with:
+
+> The gmail skill isn't authenticated for this agent yet. Open Agent Settings → Skills → gmail and click "Authenticate", or run `manigent gmail auth` on the runner.
+
+## Step 1 — Pick the subcommand
+
+| Marker / intent | Command |
+|---|---|
+| "any emails from / about …" | `manigent gmail search "<query>" --max 20` |
+| "open the email …" | `manigent gmail get <message-id>` |
+| "what attachment was on …" | `manigent gmail attachment <message-id> <attachment-id> --out <path>` |
+| "send an email to …" | `manigent gmail send --to … --subject "…" --body -` (pipe body via stdin) |
+| "archive this / clear these out of my inbox" | `manigent gmail archive <id> [<id> …]` |
+| "archive everything from …" | `manigent gmail archive -q "<query>" --max N --dry-run` first, then re-run without `--dry-run` |
+| "put that back in my inbox" | `manigent gmail archive <id> --undo` |
+| List labels | `manigent gmail labels` |
+
+The CLI self-resolves `--token` from `$MANIGENT_AGENT_DIR` — omit it.
+
+## Step 2 — Fetching mail on a schedule
+
+These commands only fetch. If your SOP has you pull mail regularly, where you
+store it, how you deduplicate it (Gmail's message `id` is stable), and how you
+track what you already fetched (e.g. an `after:<epoch>` search term from your
+last run) is up to that SOP.
+
+## Step 3 — Interactive use
+
+For search / read / send, pipe long bodies via stdin (`--body -`), parse the
+JSON output, and synthesize a conversational reply. Don't paste raw JSON into
+chat.
+
+## Step 3b — Archiving (the only write op besides send)
+
+Gmail archive == removing the `INBOX` label. Nothing is deleted: the mail stays
+in All Mail and `manigent gmail archive <id> --undo` puts it back. Say that
+when you report — it's what makes a bulk archive safe to accept.
+
+```bash
+manigent gmail archive 18f2a1b3c4d5e6f7                       # one message
+manigent gmail archive -q "from:news older_than:30d" --max 50 --dry-run
+manigent gmail archive -q "from:news older_than:30d" --max 50  # for real
+```
+
+**Query mode: ALWAYS `--dry-run` first**, show the user the matched subjects,
+and only re-run without the flag after they confirm. Explicit-id archive needs
+no confirmation step — the user already named the message.
+
+Output JSON carries `matched` (with subject/from/date in query mode),
+`archived`, and `failed: [{id, error}]`. Two things to surface in your reply:
+- `truncated: true` means the match count hit `--max` and more mail may match —
+  tell the user, and offer to re-run with a higher `--max`.
+- A non-empty `failed` names the specific messages that didn't move; the rest
+  did. Re-running is safe — archiving an already-archived message is a no-op.

manigent/_catalog/skills/google-calendar/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: google-calendar
+description: >
+  Google Calendar (list / get / create / update / delete events). Invoked via
+  `manigent gcal {calendars,list-events,get,create,update,delete,auth,revoke}`.
+  Requires Google OAuth — Authenticate via Agent Settings → Skills →
+  google-calendar. The token resolves from
+  `$MANIGENT_AGENT_DIR/skill-hub/state/google-calendar/`.
+---
+
+# /manigent:google-calendar
+
+Google Calendar via the `manigent gcal` CLI.
+
+## Step 0 — Preflight
+
+Token at `$MANIGENT_AGENT_DIR/skill-hub/state/google-calendar/token.json` is required.
+If absent, reply: "Open Agent Settings → Skills → google-calendar and click Authenticate."
+
+## Step 1 — Pick the subcommand
+
+| Intent | Command |
+|---|---|
+| List user's calendars | `manigent gcal calendars` |
+| "what's on my calendar this week?" | `manigent gcal list-events --time-min ... --time-max ...` |
+| Fetch one event | `manigent gcal get <event-id>` |
+| Create event | `manigent gcal create --summary "..." --start ... --end ... [--attendees a,b,c]` |
+| Patch event | `manigent gcal update <event-id> --fields '{"summary":"new"}'` (or `--fields -` stdin) |
+| Delete event | `manigent gcal delete <event-id>` |
+
+`--token` self-resolves — omit it.
+
+## Step 2 — Interactive use
+
+Parse JSON output and respond conversationally. Times are RFC3339 UTC
+(`2026-04-20T00:00:00Z`).
+
+## Step 3 — Fetching events on a schedule
+
+These commands only fetch (and edit). If your SOP has you pull events
+regularly, where you store them, how you deduplicate them (the event `id` is
+stable per occurrence; `iCalUID` is shared across a recurring series), and how
+you track what you already fetched (e.g. a rolling `--time-min` / `--time-max`
+window) is up to that SOP.

manigent/_catalog/skills/google-drive/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: google-drive
+description: >
+  Google Drive read-only (search / read). Invoked via
+  `manigent gdrive {search,get,auth,revoke}`. Requires Google OAuth
+  (drive.readonly) — Authenticate via Agent Settings → Skills → google-drive.
+  Google Docs / Sheets / Slides export as text / first-tab TSV.
+---
+
+# /manigent:google-drive
+
+Drive read access via the `manigent gdrive` CLI.
+
+## Step 0 — Preflight
+
+Token at `$MANIGENT_AGENT_DIR/skill-hub/state/google-drive/token.json` required.
+If absent, reply: "Open Agent Settings → Skills → google-drive and click Authenticate."
+
+## Step 1 — Pick the subcommand
+
+| Intent | Command |
+|---|---|
+| "find files about X" | `manigent gdrive search "name contains 'X'"` |
+| Read one file body | `manigent gdrive get <file-id>` |
+
+Drive query syntax: `name contains 'foo'`, `mimeType = '...'`,
+`'<folder>' in parents`, `modifiedTime > '2025-01-01T00:00:00Z'`. See
+https://developers.google.com/drive/api/guides/search-files.
+
+## Step 2 — Interactive read
+
+`get` returns `{id, name, mime_type, modified_time, content}`. Google Docs /
+Slides export as text and Sheets as first-tab TSV. Binary types and bodies over
+256 KB return `content: null` — open those via the file's `web_view_link`
+(from `search`).
+
+## Step 3 — Fetching files on a schedule
+
+These commands only fetch. If your SOP has you pull files regularly, where you
+store them, how you deduplicate them (the file `id` is stable), and how you
+track what you already fetched (e.g. a `modifiedTime > '<last run>'` search
+term) is up to that SOP.

manigent/_catalog/skills/google-drive-write/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: google-drive-write
+description: >
+  Google Sheets read + write (per-target). Each named target binds one
+  spreadsheet's named tab + id-column. Invoked via
+  `manigent gdrive-write {read-rows,append-rows,update-cell,auth}`. Separate
+  from `google-drive` so the sheets-write OAuth scope is opt-in (one agent
+  can hold both tokens). No sync trigger — used inline by content-engine
+  pipelines (e.g. marketing template's instagram agent: read brief sheet →
+  generate image → write back).
+---
+
+# /manigent:google-drive-write
+
+Google Sheets read+write via the `manigent gdrive-write` CLI.
+
+## Step 0 — Preflight
+
+Token at `$MANIGENT_AGENT_DIR/skill-hub/state/google-drive-write/token.json`
+required. Configure `sheet_targets` via Agent Settings → Skills →
+google-drive-write → Configure.
+
+## Step 1 — Pick the subcommand
+
+| Intent | Command |
+|---|---|
+| Read all rows | `manigent gdrive-write read-rows --target <name>` |
+| Append rows | `manigent gdrive-write append-rows --target <name> --rows-file rows.json` |
+| Update one cell | `manigent gdrive-write update-cell --target <name> --row-id <id> --column <col> --value <val>` |
+
+Each target's `name` is the logical key the LLM uses; `spreadsheet_id`,
+`sheet_name`, and `row_id_column` are configured separately.
+
+## Step 2 — Append shape
+
+`--rows-file` is a JSON list of dicts keyed by column name. Unknown keys
+are silently dropped (extend the Sheet header first if you need a new
+column). Missing keys are written as empty strings. Stream via stdin:
+`manigent gdrive-write append-rows --target ideas --rows -`.
+
+## Step 3 — Update by primary key
+
+`update-cell` looks up the row whose `row_id_column` matches `--row-id`
+and writes `--value` into `--column`. Errors verbosely on missing
+column / missing row so the agent can self-correct.

manigent/_catalog/skills/google-drive-write/starter_config.jsonc

@@ -0,0 +1,45 @@
+{
+  // google-drive-write — read AND write N configured Google Sheet targets.
+  //
+  // Each entry in `sheet_targets` is one tab on one spreadsheet the agent can
+  // operate on. Tools (`read_sheet_rows`, `append_sheet_rows`,
+  // `update_sheet_cell`) take a `target_name` selecting which entry to use.
+  //
+  // The OAuth scope is `spreadsheets` (write); install this MCP separately
+  // from the read-only `google-drive` MCP so you can opt into each
+  // independently.
+  //
+  // Per-entry fields:
+  //   name            — logical key the LLM passes as `target_name`. Must be
+  //                     unique within `sheet_targets`.
+  //   spreadsheet_id  — the long id in the Sheet URL between /d/ and /edit.
+  //                     Inline the literal id OR use a ${VAR} placeholder
+  //                     resolved from runner env (e.g. ${MARKETING_SHEET_ID}).
+  //   sheet_name      — the tab name (NOT the file name). Defaults to
+  //                     "Sheet1" in a brand-new Sheet.
+  //   row_id_column   — header name of the primary-key column used by
+  //                     update_sheet_cell to find rows. Optional; defaults to
+  //                     "id". The marketing pipeline expects "id".
+  //
+  // Each target's sheet MUST have a header row in row 1; tools key cell
+  // values on it. For the marketing pipeline, paste this header into row 1
+  // of the `ideas` tab:
+  //   id  created_at  channel  idea_title  idea_brief  grade  grade_rationale
+  //   sign_off  draft_body  drafted_at  publish_sign_off  notes
+
+  "sheet_targets": [
+    {
+      "name": "ideas",
+      "spreadsheet_id": "${MARKETING_SHEET_ID}",
+      "sheet_name": "ideas",
+      "row_id_column": "id"
+    }
+    // Add more entries here to operate on additional tabs / sheets, e.g.:
+    // {
+    //   "name": "ops",
+    //   "spreadsheet_id": "${OPS_SHEET_ID}",
+    //   "sheet_name": "tasks",
+    //   "row_id_column": "id"
+    // }
+  ]
+}

manigent/_catalog/skills/grill-me/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: grill-me
+description: >
+  Narrow a fuzzy decision down to the real question before anyone spends a
+  project on the wrong one. INVOKE when ANY of: (1) the user says "grill me",
+  "push back on this", "help me think this through", or "what am I really
+  deciding"; (2) in a DM, the user brings a decision they keep putting off, or
+  asks for research or a comparison that is really in service of one decision
+  ("compare 10 CRMs"); (3) `broaden-options` hands off because the decision the
+  options serve is unclear; (4) you are a participant in a project whose
+  request is a decision and you hold a brief for it. Two modes. In a DM: one
+  question per turn, up to about 8 turns, ending in a five-part brief and a
+  fixed self-graded closing line. Inside a project: never interview the user;
+  review the plan against the brief once before acceptance and the final
+  report against "what would change my mind" once.
+---
+
+# Grill me — find the real question
+
+People arrive with the question they can say out loud ("which CRM?"). The
+decision usually sits one or two layers under it ("do we keep selling to
+agencies, or move to in-house teams?"). This skill gets there by asking, and
+writes down what it found as a **brief** that the user — and any project that
+follows — can work against.
+
+## § Pick the mode first
+
+Read your own prompt before anything else:
+
+- **DM mode** — your role block says `== DIRECT MESSAGE CONVERSATION ==` or
+  `== DM COORDINATOR ROLE ==`: you are in a 1:1 conversation with the user.
+  Follow § DM mode.
+- **Project mode** — anything else: a `== WORKER ROLE ==`, a project
+  coordinator role, a workroom, a `milestone-*` room, a `PLAN.md` in the
+  synced files. Follow § Project mode.
+
+If you cannot tell, treat it as project mode. Wrongly staying quiet costs one
+skipped interview; wrongly interviewing inside a project costs the user's
+trust in the whole team.
+
+## § DM mode
+
+### The interview
+
+1. **One question per turn.** Never two, never a numbered list of questions,
+   never "a few quick questions". One question, then stop and wait.
+2. **Each question builds on the user's last answer.** Quote or name the
+   thing they just said that you are pulling on. A question that could have
+   been asked before their last answer is the wrong question.
+3. Before your question, add at most two sentences: what you just heard, and
+   (when it changed) the draft brief part it moved. No lecturing, no advice,
+   no options yet — options are `broaden-options`' job.
+4. Dig in roughly this order, skipping anything already clear:
+   - **The decision** — what will actually be chosen, by whom, by when?
+   - **The real question** — why does this decision matter now? What would
+     be different if they got it right? Keep asking "and that matters
+     because…?" until the answer stops being a means to something else.
+   - **The current bet** — if they had to choose today, what would they pick?
+     (They almost always have one. Ask for it plainly.)
+   - **What would change their mind** — what evidence, if they saw it, would
+     flip the bet? Push for something observable, not "if it turns out badly".
+   - **What is out of scope** — what are they NOT deciding here?
+5. Keep a draft brief in your head (the five parts below) and update it after
+   every answer.
+
+### When to stop
+
+Stop asking and write the brief when **either**:
+
+- you have asked about **8 questions**, or
+- the draft brief has **not changed for 2 turns in a row** — the last two
+  answers confirmed it rather than moved it.
+
+Also stop if the user says "enough", "just write it up", or similar. Do not
+stretch to 8 if the brief is already stable.
+
+### The brief
+
+Write it in this shape, in the user's own words wherever possible:
+
+```
+**Decision:** <what will be chosen, by whom, by when>
+**Real question:** <the question underneath, that the decision actually serves>
+**Current bet:** <what they would pick today, and the one-line why>
+**Evidence that would change my mind:** <observable things that would flip the bet>
+**Out of scope:** <what this decision is not about>
+
+Real question changed from your first message: yes (self-graded)
+```
+
+### The closing line — fixed wording, always last
+
+The brief ALWAYS ends with exactly one closing line, and it is the last line
+of the message:
+
+```
+Real question changed from your first message: yes (self-graded)
+```
+
+or
+
+```
+Real question changed from your first message: no (self-graded)
+```
+
+- You fill in `yes` or `no` yourself. Compare the **Real question** you just
+  wrote with the user's FIRST message in this conversation. `yes` if a
+  reader would say they are about different things (the first message asked
+  "which CRM", the real question is about which customers to serve); `no` if
+  the brief only sharpened or restated what they first asked.
+- Copy the wording character for character: no bold, no bullet, no trailing
+  punctuation, lowercase `yes`/`no`, then ` (self-graded)`. Adoption measures
+  parse this line with a fixed prefix; any variation is lost from the count.
+- Never omit it, even if the brief is short or the user cut the interview off.
+
+Between the brief and the closing line, offer — in one sentence — the
+obvious next step: widen the options with `broaden-options`, or take the
+brief into a project. Do not start either unasked, and never put the offer
+after the closing line.
+
+## § Project mode
+
+**Inside a project you NEVER interview the user. Not in any room, not once,
+not "just one quick question".** Installing this skill cannot enforce that
+rule, so it is stated here and it is absolute. The user agreed to a plan;
+they did not agree to be grilled through a coordinator. If you think a
+question needs the user's answer, write it as an objection (below) and let
+the coordinator decide whether to raise it.
+
+### Get the brief
+
+Look, in order, in the project request, the `shared-context` room and its
+files, and your delegation message, for a brief with the five parts above
+(often pasted from a grill-me DM). If there is none, write a draft brief
+yourself from the project request alone, and mark every part you inferred
+`(inferred)`. Do not ask anyone to supply it.
+
+### Two reviews, each exactly once
+
+1. **Plan review — once, before the plan is accepted.** Read `PLAN.md`
+   against the brief. For each milestone, ask: which brief part does this
+   serve? Raise an objection for any milestone that serves none, any brief
+   part no milestone serves, and any milestone that works on something the
+   brief puts **Out of scope**. Post the review once in `shared-context`;
+   do not re-review later drafts unless the coordinator asks.
+2. **Final-report review — once, at the final report.** Read the completion
+   report against **Evidence that would change my mind**. Say whether the
+   project produced that evidence, produced the opposite, or did not look.
+   Post it once in your workroom.
+
+### Every objection names the brief part
+
+Each objection names the milestone and the brief part it fails to serve, in
+this shape:
+
+```
+- <milestone name> does not serve **<brief part>**: <one sentence why>. Suggest: <one-line change>.
+```
+
+The brief part is one of: **Decision**, **Real question**, **Current bet**,
+**Evidence that would change my mind**, **Out of scope**. An objection that
+names no brief part is a taste comment — drop it. If the plan serves every
+part, say so in one line and raise nothing.
+
+## § Anti-patterns
+
+- Asking two questions in one turn, or a list "to save time".
+- Offering options, advice or a recommendation during the interview.
+- Asking a question the user already answered.
+- Running past ~8 questions because the brief "could be sharper".
+- Paraphrasing the closing line, bolding it, or putting anything after it.
+- In a project: any question addressed to the user, directly or relayed.
+- In a project: re-running either review on every plan edit.

manigent/_catalog/skills/homekit/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: homekit
+description: >
+  Apple HomeKit / Apple Home control via the macOS `shortcuts` CLI. The user
+  builds the Shortcuts (Bedtime, Away-mode, Set Bedroom Temp); this skill just
+  enumerates and invokes them through `manigent homekit list-shortcuts` and
+  `manigent homekit run-shortcut "<name>"`. macOS 12+ only. No OAuth, no
+  config. If the runner is non-macOS, the CLI errors out — reply that the
+  skill is unavailable on this host.
+---
+
+# /manigent:homekit
+
+Two Bash subcommands. The Shortcuts app is the contract; this skill never
+reinvents device primitives or duplicates the editor.
+
+## Step 1 — Discover
+
+When you first need to control devices on a new agent, call
+`manigent homekit list-shortcuts` once and remember the result (or cache it
+under `memory/learnings/` if you'll use it across sessions).
+
+## Step 2 — Invoke
+
+```bash
+manigent homekit run-shortcut "Bedtime"
+manigent homekit run-shortcut "Set Bedroom Temp" --input -   # piped stdin
+```
+
+Returns `{ok, exit_code, stdout, stderr}`. Report back conversationally — e.g.
+"Set Bedroom Temp ran OK." Don't paste raw stdout if it's empty.
+
+## Step 3 — Errors
+
+The CLI exits 1 with a clear message if the platform isn't macOS or the
+`shortcuts` binary is missing. Surface that error to the user without
+re-formatting; they need to know the host can't drive HomeKit.

manigent/_catalog/skills/http-api/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: http-api
+description: >
+  Generic HTTP client — `manigent http-api get|post|put|patch|delete <url>`
+  with `-H`, `--query`, `--data`/`--json`, and a curl-style session jar
+  (`--save-session`/`--session`) so login is just a POST that writes cookies,
+  with `--expect-location`/`--expect-status` to declare what success looks
+  like (a wrong password is an ordinary 3xx, not an error status). `$VAR` /
+  `${VAR}` in header values expand from the environment, so auth secrets stay
+  out of argv. No config.
+---
+
+# /manigent:http-api
+
+Drive any HTTP/REST API via the `manigent http-api` CLI.
+
+Fetching data on a schedule: these commands only fetch (and write). Where the
+results are stored, how they are deduplicated, and how incremental fetches are
+tracked (a `since` / cursor / page parameter passed via `--query`) is up to
+your agent's SOP.
+
+## Commands
+
+A general-purpose curl-shaped client for driving a live API — log in, hold the
+session, then read/write.
+
+```
+manigent http-api get    <url> [options]
+manigent http-api post   <url> [options]     # + --data / --json
+manigent http-api put    <url> [options]     # + --data / --json
+manigent http-api patch  <url> [options]     # + --data / --json
+manigent http-api delete <url> [options]     # + --data / --json (body optional)
+```
+
+### Options
+
+| Option | Meaning |
+|--------|---------|
+| `-H, --header "Name: value"` | Repeatable. `$VAR` / `${VAR}` in the value is expanded from the **environment** (unset → empty string) — so `-H "Authorization: Bearer $ICS_TOKEN"` keeps the secret out of argv/logs/jar. |
+| `--query "k=v"` | Repeatable query-string param. |
+| `--data "k=v"` | Repeatable form field → `application/x-www-form-urlencoded`. |
+| `--json '<raw>'` | Raw JSON body, curl semantics: repeatable + concatenated, `@file` and `@-` (stdin) supported; sets `Content-Type` **and** `Accept: application/json` (an explicit `-H` wins). Mutually exclusive with `--data`. |
+| `--session <jar>` | Load cookies from a jar (curl `-b`). |
+| `--save-session <jar>` | Write captured cookies to a `0600` JSON jar (curl `-c`). |
+| `--follow` / `--no-follow` | **Default `--no-follow`.** A login's `3xx` *is* the auth signal — `302` or `303` (Rails and most POST-redirect-GET frameworks emit `303`) with `Location: /` = ok, `/login` = fail; auto-following would mask a failed login as a final `200`. |
+| `--expect-location <glob>` | **Declare where a successful request lands.** The `Location` header is resolved against the request URL first (so `/`, `https://host/` and `../x` all normalize), then glob-matched. A pattern starting with `/` matches the URL **path** — `'/'` is exact, `'/dashboard*'` is a prefix; any other pattern matches the whole absolute URL. Under `--follow` (no `Location` on the final response) it matches the final URL instead, so the flag reads as "where did I end up" either way. Unmet → exit `23` **and the `--save-session` jar is not written**. Note `/dashboard` and `/dashboard/` are different paths — write `'/dashboard*'` if the app may add the slash. |
+| `--expect-status <spec>` | **Declare the acceptable status(es)** — `'200'`, `'2xx'`, `'200,303'`; `x` is a wildcard digit. Covers the two shapes `--expect-location` cannot see: a login form re-rendered at `200`, and an API returning JSON `401`. Unmet → exit `23`, jar not written. A malformed spec exits `2` **before any request is sent**. |
+| `--output body\|json\|full` | `body` (default) = raw text; `json` = pretty-printed (errors if the body isn't JSON); `full` = envelope `{status, reason, url, location, history, headers, body}` — read this to inspect a login's status + `Location`. |
+| `--timeout <s>` | Per-request timeout (default 30). |
+| `--fail` | Opt into curl-style non-zero exit on HTTP status ≥ 400. |
+
+### Session jar
+
+The jar is **cookies-only**: `{"cookies": {name: value}}` written `0600`.
+Cookies are captured from *every* response — **including a 302's own
+`Set-Cookie`** — so `--save-session` works even with `--no-follow`. Login is
+therefore just a `post` that writes a jar; there is no auth subcommand, which
+keeps it general across cookie / token / OTP APIs. (Legacy
+`{"cookies", "headers"}` jars still load; the `headers` half is ignored.)
+
+**The jar is written only when the command exits `0`.** An unmet `--expect-*`,
+a `--fail` status, or a render error all suppress the write, so a failed login
+can never replace a working session with the login page's anonymous cookie.
+Without `--expect-*` there is nothing to fail against — a bad password still
+looks like success — which is why a login that writes a jar should always
+declare an expectation.
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Response received — **any** HTTP status (incl. 4xx/5xx); body on stdout. |
+| `2` | Usage error (bad `-H`/`--query`/`--data`, `--json`+`--data` together, bad `--output`, body on a GET). |
+| `6` | Session/jar I/O error (missing/unreadable/unwritable jar). |
+| `7` | Network error (DNS, connect, timeout, TLS, bad URL). |
+| `22` | HTTP status ≥ 400 **and** `--fail` was passed. Jar not written. |
+| `23` | A declared `--expect-location` / `--expect-status` did not match. Body still printed, one-line reason on stderr, jar not written. Wins over `22` when both fire — the more specific declaration reports. |
+
+4xx/5xx return `0` by default so structured error payloads (e.g. a JSON
+`400`) stay readable.
+
+### Worked example — login, then authed GET
+
+```bash
+export ICS_TOKEN=...              # if the API is token-based instead of cookie
+
+# 1) Log in. POST the form, DON'T follow the redirect, save the cookie jar,
+#    and DECLARE where a successful login lands. Without --expect-location a
+#    wrong password returns 3xx + Set-Cookie + exit 0, exactly like success.
+manigent http-api post https://ics.example/login \
+  --data "username=alice" --data "password=$ICS_PW" \
+  --no-follow --save-session /tmp/ics.jar --expect-location '/' --output full
+# exit 0  => landed at "/": authenticated, cookie captured off the 3xx
+# exit 23 => landed elsewhere (e.g. "/login"): jar NOT written, any previous
+#            session left intact; stderr says where it actually landed.
+
+# API-style login (JSON 200 on success, 401 on failure)? Declare the status
+# instead of the destination:
+manigent http-api post https://api.example/session \
+  --json "{\"user\":\"alice\",\"pw\":\"$ICS_PW\"}" \
+  --save-session /tmp/api.jar --expect-status 200 --output json
+
+# 2) Reuse the session on subsequent calls.
+manigent http-api get https://ics.example/reports --session /tmp/ics.jar --output json
+
+# 3) Token APIs need no jar — pass the header, read the secret from env:
+manigent http-api get https://api.example/v1/me \
+  -H "Authorization: Bearer $ICS_TOKEN" --output json
+
+# 4) Writes work the same way (PUT/PATCH/DELETE take --data or --json):
+manigent http-api patch https://api.example/v1/items/42 \
+  --session /tmp/ics.jar --json '{"status":"archived"}' --output full
+manigent http-api delete https://api.example/v1/items/42 --session /tmp/ics.jar --fail
+```
+
+Credentials are never echoed: request headers/cookies/body are not logged, and
+only the response you asked for is printed.