atris 3.15.0 → 3.15.12

package/AGENTS.md

@@ -15,7 +15,9 @@ Run this first. Follow the output.
 | File | Purpose |
 |------|---------|
 | `atris/PERSONA.md` | Communication style (read first) |
-| `atris/TODO.md` | Current tasks |
+| `atris task` | Current tasks, claims, dialogue, proof |
+| `.atris/state/tasks.projection.json` | Readable task projection for UIs/agents |
+| `atris/TODO.md` | Rendered/legacy task view only |
 | `atris/MAP.md` | Navigation (where is X?) |
 
 ## Workflow
@@ -31,16 +33,45 @@ CHECK → atris review (verify + cleanup)
 - [ ] 3-4 sentences max per response
 - [ ] Use ASCII visuals for planning
 - [ ] Check MAP.md before touching code
-- [ ] Claim tasks in TODO.md before working
-- [ ] Delete tasks when done
+- [ ] Run `atris task list` or `atris task next` before picking work
+- [ ] Claim tasks with `atris task claim <id> --as <agent>`
+- [ ] Finish tasks with proof via `atris task finish <id> --proof "..."`
+- [ ] Treat `atris/TODO.md` as a rendered view; do not manually use it as the source of truth
 
 ## Anti-patterns
 
 - Don't explore codebase manually (use MAP.md)
 - Don't skip visualization step
 - Don't leave stale tasks
+- Don't hand-edit TODO.md for active task ownership
 - Don't write verbose docs
 
 ---
 
-**Protocol:** See `atris/atris.md` for full spec.
+**Protocol:** See `atris/atris.md` for full spec.
+
+<!-- ATRIS_BRAIN_COMPILE:START -->
+## Atris Brain Compile
+
+This workspace has a compiled agent brain.
+
+On session start, activate it first:
+`atris brain activate --root /Users/keshavrao/arena/atris-cli --verify`
+
+Load these first:
+- `atris/now.md`
+- `atris/brain/STATUS.md`
+- `atris/brain/self_improvement_ledger.md`
+- `atris/wiki/concepts/sync-language.md`
+- `atris/skills/activation/SKILL.md`
+- `atris/MAP.md`
+- `atris/TODO.md`
+
+First-message rule: follow the sync-language contract before writing to the operator.
+Purpose: optimize for decision-speed; lead with the move, then use descriptions only when they help the operator act.
+Shape: `<operator>, today is about <move>` -> `I picked this because <why now>` -> `Ready: <draft/proof/context>` -> `Go deeper: <paths>`.
+Definitions: operator = current person or agent; move = one concrete high-leverage workflow; why now = business reason; ready = prepared action or proof; paths = 2-4 optional deeper views.
+
+Re-run after meaningful work:
+`atris brain compile --root /Users/keshavrao/arena/atris-cli`
+<!-- ATRIS_BRAIN_COMPILE:END -->

package/README.md

@@ -41,7 +41,7 @@ Then read the workspace's `atris/atris.md` and follow it exactly. `atris.md` is
 |------|---------|
 | `atris/atris.md` | Main instructions for agents working in this repo |
 | `atris/MAP.md` | Navigation index with file:line refs |
-| `atris/TODO.md` | Shared task queue |
+| `atris/TODO.md` | Human-readable task view |
 | `atris/logs/YYYY/YYYY-MM-DD.md` | Daily log, inbox, notes, completions |
 | `atris/features/` | Feature packs with `idea.md`, `build.md`, `validate.md` |
 | `atris/skills/` | Reusable skills for agents |
@@ -137,7 +137,7 @@ atris business record atris/reports/2026-04-12-operator-recap.md --outcome mixed
 | `atris autopilot` | Guided loop with approvals |
 | `atris log` | Add inbox items to today's journal |
 | `atris status` | Show active work and completions |
-| `atris task` | Local agent task plane with atomic claims and TODO import |
+| `atris task` | Durable local task state with claims, dialogue, review episodes, JSON export, TODO import, TODO render, board, and sync dry-run |
 | `atris learn` | Manage structured learnings |
 | `atris ingest` | Stage raw evidence into `atris/context/` and compile into `atris/wiki/` |
 | `atris loop` | Refresh wiki health, stale/orphan signals, and next ingest candidates |
@@ -154,7 +154,7 @@ atris business record atris/reports/2026-04-12-operator-recap.md --outcome mixed
 - `atris wiki --private` stores local-only sensitive notes under `.atris/presidio/`
 - `atris loop` refreshes `atris/wiki/STATUS.md` and `atris/wiki/log.md`, flags stale/orphan pages, and suggests the next ingest
 - `atris activate` loads the current wiki status so the next session starts with project memory, not just tasks
-- `atris task` keeps a local SQLite task plane for agents while `atris/TODO.md` remains the readable project board
+- `atris task` keeps durable local task state and append-only events for agents while `atris/TODO.md` remains a readable regenerated project board. Use `atris task new`, `atris task delegate "..." --to <owner>`, `atris task day`, `atris task next`, `atris task say`, and `atris task finish` for the natural loop; add `--json` for headless agents. Use `atris task serve` to open the local Task Factory board with goals, work streams, lineage, proof, lessons, and the compounding chain. Every change refreshes `.atris/state/tasks.projection.json` for web/desktop. Use `atris task sync --dry-run` to preview the canonical Supabase/Swarlo task writes before any cloud mutation. Use `--via swarlo` on delegation when the live coordination layer should claim/report from the same task record. Use `--create-next` with review/finish to turn a `--next` suggestion into the next durable task. Use `atris task setup --import-todo` to bootstrap, `atris task review` to write an RSI episode, and `atris task render` to rebuild markdown if it gets clobbered. In cloud business workspaces, Supabase `tasks` is the source of truth and Swarlo is the live claim/report layer.
 - `atris experiments` runs small test packs in `atris/experiments/`
 - `atris pull` and `atris push` sync cloud workspaces and journals
 - `atris live` keeps a business brain fresh by checking/fixing the workspace, pushing local state, pulling cloud state, and pushing again after local changes go quiet

package/atris/atris.md

@@ -58,18 +58,43 @@ Labels used below:
 - `guarded` — checked by code or a pre-commit hook; bypassing is a bug
 - `expected` — convention; honor it or stop
 
-## task shape
+## task source of truth
+
+Use `atris task` as the source of truth for active work. It stores durable local
+SQLite state plus append-only task events, and refreshes
+`.atris/state/tasks.projection.json` for desktop/web UIs. `atris/TODO.md` is a
+rendered/legacy view and can be rebuilt with `atris task render`; do not rely on
+manual TODO.md edits for ownership.
+
+Core loop:
+
+```bash
+atris task list
+atris task delegate "<title>" --to <owner> --tag <tag>
+atris task delegate "<title>" --to <owner> --via swarlo --tag <tag>
+atris task day
+atris task next
+atris task claim <id> --as <agent>
+atris task note <id> "<context, blocker, decision, or handoff>"
+atris task finish <id> --proof "<tests, screenshot, diff, or receipt>"
+atris task review <id> --lesson "<what improved>" --next "<next task>"
+```
+
+Headless agents should add `--json` where available and read
+`.atris/state/tasks.projection.json` for a compact board view.
+Swarlo is the live coordination layer for claims, heartbeats, and reports; the
+task row/event stream remains the durable source of truth.
 
-Every task in `TODO.md`:
+Every task record should carry:
 
 ```
-- **T#:** <title> [tier] [kind]
-  **Owner:** <slug>
-  **Files:** <paths touched>
-  **Exit:** <observable done condition>
-  **Verify:** <shell command, exits 0 on success>
-  **After:** <T# deps or none>
-  **Rollback:** <commit/checkpoint or "none (gray)">
+Title: <small work packet>
+Owner: <agent or unclaimed>
+Objective: <why this matters>
+Context: <links/files/decisions>
+Exit: <observable done condition>
+Verify: <shell command or concrete proof>
+Next: <suggested follow-up task>
 ```
 
 | Field | Meaning | Enforcement |
@@ -87,7 +112,7 @@ Verify cannot be a raw shell shortcut; it must call a rubric or test that can fa
 ## routing
 
 Before picking up work, decide scope:
-- single project → route to that project's `atris/team/` and `TODO.md`
+- single project → route to that project's `atris/team/` and `atris task` queue
 - crosses projects → route to `atris/team/cross-project-architect/` and plan the dependency order first
 
 The human is the constructor. You multiply. Handoff fidelity lives in the files, not in context.
@@ -98,8 +123,8 @@ Move one task at a time through plan → do → review.
 
 - **plan** — read relevant files, produce an ASCII visualization, wait for approval. No code.
 - **plan-review** — the validator reads the plan fresh and signs off with `SIGNOFF:` or halts with `REJECT:\nFIX:`. Plan does not move to do without signoff. Codex is optional escalation when `ATRIS_USE_CODEX=1` or the task carries `[codex]`.
-- **do** — claim the task (move it to In Progress with `Claimed by:` and a timestamp), execute step by step, update `MAP.md` and the journal as reality changes.
-- **review** — run the task's `Verify:` command, read the diff, run the relevant tests, append a one-line lesson to `lessons.md`, move the task to Completed.
+- **do** — claim the task with `atris task claim <id> --as <agent>`, execute step by step, add notes as reality changes, update `MAP.md` and the journal when needed.
+- **review** — run the task's verification, read the diff, run the relevant tests, finish with `atris task finish <id> --proof "..."`, and add the lesson/next task with `atris task review`.
 
 State the next stage:
 
@@ -149,7 +174,7 @@ Context is a cache. Disk is truth. Route discoveries as they happen:
 | You discover... | Write to... |
 |---|---|
 | a code location | `MAP.md` (file:line) |
-| a new task | `TODO.md` |
+| a new task | `atris task new "<title>"` |
 | a decision or tradeoff | journal `## Notes` |
 | something learned | `lessons.md` (one line) |
 | work finished | journal `## Completed` (C#) |

package/atris/features/company-brain-sync/build.md

@@ -0,0 +1,140 @@
+# Company Brain Sync Build Plan
+
+## Current Patch
+
+The immediate DoorDash lane now follows the correct company-brain model:
+
+- `atris push` keeps the business root as the path root so `doordash/atris/MAP.md` maps to cloud `/atris/MAP.md`
+- business `pull` and `push` default to the `atris/` scope
+- root-level duplicates such as `MAP.md`, `TODO.md`, and `security-report.md` are ignored by default
+- manifests record the local workspace root to prevent a manifest from one folder authorizing pushes from another folder
+- real cloud deletes require `--delete`
+- `atris sync <business>` runs the safe operator sequence as one command
+- `atris sync` auto-detects the business slug inside a pulled business workspace
+- `lib/company-brain-sync.js` contains the pure classification core for Notion/Drive/GitHub-style sync decisions
+- conflict review packet generation exists as a pure artifact builder
+- `pull --fail-on-conflict` writes the conflict review packet before `atris sync` stops
+- `atris sync --watch` watches the local `atris/` brain, debounces local edits, periodically checks cloud using the same safe sync cycle, and keeps retrying after transient failures
+- `atris sync --status` gives a local, nonengineer-readable status card: detected business, brain file count, manifest health, conflict packets, and watcher heartbeat
+- `atris sync --review` prints the latest local conflict review packet without credentials or cloud calls
+- `atris sync --resolve local|cloud|both|merge` applies the latest conflict packet's chosen side or a safe deterministic merge back into local `atris/` files, then tells the operator to dry-run before publishing
+- local safety commands (`--status`, `--review`, `--resolve`) route to company-brain sync even if business slug detection is missing or broken
+- successful pulls cache base content under `.atris/sync/base/` so future conflict packets can include `.base` files for safe merge resolution
+- real sync/watch cycles write `.atris/sync/status.json` as the local heartbeat; `--dry-run` still writes nothing
+
+## Desired Sync Engine
+
+Move from command sequencing to a single sync engine with explicit state.
+
+### State Model
+
+For each cloud path under `/atris/`, track:
+
+- base hash: last version both local and cloud agreed on
+- local hash: current local file
+- remote hash: current cloud file
+- local mtime: local edit signal
+- remote version or commit: cloud edit signal
+- actor metadata when available
+
+### Change Classes
+
+The engine should classify every path as:
+
+- unchanged
+- local created
+- local updated
+- local deleted
+- remote created
+- remote updated
+- remote deleted
+- both changed same content
+- both changed conflicting content
+
+Initial classifier coverage exists in `test/company-brain-sync.test.js`.
+
+### Actions
+
+Default actions:
+
+- pull remote-only changes
+- push local-only creates/updates
+- preserve local work on conflicts
+- never delete cloud by default
+- never delete local untracked files by default
+- write a sync report for review
+
+### Conflict UX
+
+A conflict should create a review artifact, not a scary merge state.
+
+Recommended local artifact:
+
+```text
+.atris/sync/conflicts/<timestamp>/<path>.local
+.atris/sync/conflicts/<timestamp>/<path>.remote
+.atris/sync/conflicts/<timestamp>/summary.md
+```
+
+The packet shape is implemented in `buildConflictReviewPacket`, and `pull --fail-on-conflict` materializes it before stopping sync.
+
+Recommended summary language:
+
+```text
+3 files need review before publishing:
+- atris/wiki/concepts/weekly-business-review.md
+- atris/TODO.md
+- atris/reports/wbr-panel-2026-04-23.md
+```
+
+### Publish UX
+
+The first local review command exists:
+
+```bash
+atris sync --review
+```
+
+It prints the latest conflict summary and tells the operator to resolve locally, then run `atris sync --dry-run`.
+
+The first resolution command exists:
+
+```bash
+atris sync --resolve local
+atris sync --resolve cloud
+atris sync --resolve both
+atris sync --resolve merge
+```
+
+It applies the selected side into local `atris/` files and keeps the conflict packet as the audit trail. `both` keeps the local version at the original path and writes the cloud version beside it as `<file>.cloud`. `merge` requires `.base`, `.local`, and `.remote` artifacts and only writes a merged file when local and cloud edits are safe: non-overlapping line ranges, or different markdown heading sections. Same-section markdown edits stay in review.
+
+Later it should also let the user ask Atris to merge semantically with model assistance when the conservative line merge refuses.
+
+### Watch UX
+
+`atris sync --watch` is the current always-on lane:
+
+- watch `doordash/atris/`
+- debounce local edits
+- fetch cloud hashes periodically
+- sync clean changes
+- pause on conflicts with a clear review summary
+- keep the process alive on transient network/API failures and retry on the next cycle
+- record a heartbeat under `.atris/sync/status.json`
+
+`atris live` should eventually delegate to the same sync engine instead of carrying a parallel implementation.
+
+## Quality Bar
+
+This lane is production-critical because it touches customer company memory.
+
+Required before broad customer use:
+
+- fixture tests for every change class
+- fixture tests for conflict artifact creation
+- status/heartbeat tests for the nonengineer "am I current?" surface
+- retry-policy tests proving watch failures do not kill the alive loop
+- fixture tests proving parent-folder junk is ignored
+- fixture tests proving no cloud deletes without explicit opt-in
+- end-to-end dry-run against a real DoorDash-shaped workspace
+- command copy that never recommends `--force` for normal use

package/atris/features/company-brain-sync/idea.md

@@ -0,0 +1,52 @@
+# Company Brain Sync
+
+## Problem
+
+Atris business workspaces are company brains, not plain folders. The canonical knowledge surface is the `atris/` folder inside each business workspace, for example `doordash/atris/`.
+
+Raw push/pull is the wrong abstraction for this surface. It makes a shared knowledge base feel like file mirroring, which creates merge anxiety and makes users responsible for sync safety.
+
+The product bar is closer to Notion, Google Drive, and GitHub:
+
+- local edits should be detected automatically
+- cloud updates should arrive without users thinking about manifests
+- conflicts should become reviewable knowledge decisions, not overwrite prompts
+- publishing should be explicit, auditable, and reversible
+
+## Principle
+
+Cloud Atris is canonical. Local Atris is a working copy. Sync publishes proposed knowledge updates into the company brain.
+
+## User Model
+
+Jonathan should be able to work inside `doordash/atris/` and run one command:
+
+```bash
+atris sync
+```
+
+He should not need to know about `--force`, `--from`, manifests, root folders, business slugs, or cloud path prefixes.
+
+## Product Shape
+
+`atris sync <business>` is the primary operator command.
+
+When run inside a pulled business workspace, `atris sync` auto-detects the business from `.atris/business.json`.
+
+It should:
+
+- scope to `atris/` by default for business workspaces
+- pull cloud truth first without destroying local work
+- detect local changes since the last known base
+- push only clean non-conflicting changes
+- block destructive deletes unless explicitly approved
+- produce a human-readable sync summary
+
+Longer term, `atris live <business>` should watch file changes and run the same sync engine continuously, similar to Google Drive local sync plus GitHub-style conflict review.
+
+## Non-Goals
+
+- Do not mirror the parent business folder by default.
+- Do not use `--force` as a normal collaboration path.
+- Do not treat conflicts as "local wins" or "cloud wins" without review.
+- Do not expose manifest internals to nontechnical customer operators.

package/atris/features/company-brain-sync/validate.md

@@ -0,0 +1,250 @@
+# Company Brain Sync Validation
+
+## Validated Now
+
+Focused tests pass:
+
+```bash
+node --test --test-name-pattern 'push|business workspace|business sync|manifest records workspace root' test/commands.test.js
+```
+
+Company brain sync classifier tests pass:
+
+```bash
+node --test test/company-brain-sync.test.js
+```
+
+Covered classifier cases:
+
+- clean local creates and updates
+- clean remote creates and updates
+- both-changed update conflict
+- held local delete
+- remote delete plus local update conflict
+- conflict summary rendering
+- conflict review packet generation with local and remote artifacts
+- conflict review packet writing to disk
+- command-path pull conflict packet builder includes `.base`, `.local`, and `.remote` artifacts
+- local `atris sync --status` command works without credentials
+- local `atris sync --review` command prints the latest conflict packet without credentials
+- local `atris sync --resolve local|cloud|both|merge` applies conflict artifacts into local `atris/` files without credentials
+- conflict packets can include `.base` artifacts, and successful pulls cache base content under `.atris/sync/base/`
+- safe merge resolution writes non-overlapping local/cloud line edits, can merge different markdown heading sections, and refuses overlapping or same-section edits
+- local safety commands route correctly even when business slug detection is unavailable
+- safe/unsafe merge-matrix cases are covered: converged same content, cloud delete, deleted both, local delete plus cloud edit, and conflicting created files
+- status rendering shows business, brain file count, conflict packets, and watcher heartbeat
+- watch failure policy keeps the alive loop retrying on transient failures
+- watch failure policy treats conflict exits as review state instead of process death
+- watch-mode snapshot detects `atris/` changes
+- watch-mode ignores runtime and OS noise
+- push planner publishes only scoped local `atris/` creates and updates
+- push planner treats scoped local deletes as gated deletes
+- push planner ignores parent-folder junk outside `atris/`
+
+Syntax checks pass:
+
+```bash
+node -c bin/atris.js
+node -c commands/business-sync.js
+node -c lib/company-brain-sync.js
+node -c commands/pull.js
+node -c commands/push.js
+```
+
+Fresh DoorDash-shaped workspace dry-run:
+
+```bash
+atris sync doordash --dry-run
+```
+
+Observed result:
+
+```text
+Syncing doordash knowledge wiki...
+scope: atris/
+...
+Pushing to DoorDash...
+Checking cloud freshness... fresh
+Already up to date.
+```
+
+Fresh DoorDash-shaped workspace real command with no local edits:
+
+```bash
+atris sync doordash
+```
+
+Observed result:
+
+```text
+Pulling DoorDash...
+Already up to date.
+122 unchanged.
+Pushing to DoorDash...
+Checking cloud freshness... fresh
+Already up to date.
+```
+
+No cloud writes were required in the validation case because the clean workspace had no local changes to publish.
+
+Local edit dry-run in a DoorDash-shaped workspace:
+
+```bash
+printf '# Sync smoke\n\nLocal-only knowledge update.\n' > atris/wiki/smoke/local-edit.md
+atris sync doordash --dry-run
+```
+
+Observed result:
+
+```text
++ atris/wiki/smoke/local-edit.md  new file  (dry run)
+1 would be pushed, 122 unchanged. (--dry-run, nothing sent)
+```
+
+Local delete dry-run in a DoorDash-shaped workspace:
+
+```bash
+rm -f atris/wiki/index.md
+atris sync doordash --dry-run
+```
+
+Observed result:
+
+```text
+x atris/wiki/index.md  deleted  (dry run)
+Deletes require an explicit real push with --delete.
+```
+
+Real delete attempt without `--delete`:
+
+```bash
+atris sync doordash
+```
+
+Observed result:
+
+```text
+Refusing to delete 1 cloud file without --delete.
+```
+
+Fresh folder true dry-run:
+
+```bash
+atris sync --dry-run
+```
+
+Observed result:
+
+```text
+122 would be pulled. (--dry-run, nothing written)
+Publish preview skipped until the pull preview is applied.
+```
+
+File count before and after stayed the same, proving dry-run did not materialize the remote brain locally.
+
+Slug auto-detection:
+
+```bash
+atris sync --dry-run
+```
+
+Observed result from a DoorDash-shaped workspace:
+
+```text
+Syncing doordash knowledge wiki...
+scope: atris/
+```
+
+Local status surface:
+
+```bash
+atris sync --status
+```
+
+Observed shape:
+
+```text
+Company brain status
+  business: doordash
+  brain: atris/ (...)
+  conflicts: none
+  watcher: ...
+```
+
+This command is local-only and does not require credentials.
+
+Local conflict review surface:
+
+```bash
+atris sync --review
+```
+
+Observed shape:
+
+```text
+Latest sync conflict review: .atris/sync/conflicts/.../summary.md
+...
+Resolve the local file, then run `atris sync --dry-run` before publishing.
+```
+
+Local conflict resolution surface:
+
+```bash
+atris sync --resolve local
+atris sync --resolve cloud
+atris sync --resolve both
+atris sync --resolve merge
+```
+
+Validated behavior:
+
+- reads the latest `.atris/sync/conflicts/...` packet
+- writes the chosen `.local` or `.remote` artifact back to the target `atris/...` file
+- `both` keeps the local artifact at the original path and writes the cloud artifact as `<file>.cloud`
+- `merge` requires `.base`, `.local`, and `.remote`, writes non-overlapping line edits or different markdown sections, and leaves overlapping or same-section edits in review
+- does not require credentials or cloud calls
+- tells the operator to run `atris sync --dry-run` before publishing
+
+## Still Needed
+
+- Publish `atris@3.15.12`.
+- Deploy the backend workspace snapshot patch from `atrisos-backend`.
+- After deploy, run a Pallet smoke:
+
+```bash
+npm i -g atris@3.15.12
+cd ~/arena/atris-business/pallet
+atris pull pallet --keep-local --only atris/wiki --timeout 120
+atris push pallet --only atris/wiki --dry-run
+```
+
+- DoorDash post-publish smoke:
+
+```bash
+cd ~/arena/atris-business/doordash
+atris wiki verify
+atris push doordash --dry-run
+```
+
+- Packaged CLI smoke already passed locally for `3.15.12`: tarball install exposes `atris pull --no-manifest` and `atris wiki verify`.
+
+This feature is safer and usable, but the "perfect sync" bar still requires more command-path fixtures and model-assisted semantic merge support.
+
+Missing validation:
+
+- local-only create pushes cleanly end-to-end
+- local-only update pushes cleanly end-to-end
+- remote-only create pulls cleanly end-to-end
+- remote-only update pulls cleanly end-to-end
+- local delete does not delete cloud without `--delete` end-to-end
+- remote delete does not destroy local modified work end-to-end
+- parent folder junk is ignored by the push planner; still needs a full command fixture
+- long-running watcher needs an integration test with a mocked local edit and no real cloud calls
+- Pallet shipped-command smoke test from a real Pallet-shaped workspace
+- npm publication after refreshing the invalid npm token
+
+## Release Gate
+
+It is fair to call this safer than raw Notion/GitHub-style customer-brain editing for scoped markdown sync after the shipped-command smoke passes.
+
+Do not call the syncs "perfect" until the missing fixture cases and model-assisted semantic-merge conflict resolution flow are complete.

package/atris/skills/imessage/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: imessage
+description: Use when an agent needs to inspect or send local macOS iMessage through Atris CLI. Triggers on iMessage, Messages.app, local text messages, chat.db, or texting someone from the user's Mac.
+version: 1.0.0
+tags:
+  - imessage
+  - local
+  - messaging
+---
+
+# iMessage
+
+Local iMessage is a Mac capability, not a cloud OAuth integration.
+
+Use Atris CLI as the control surface.
+
+1. Check availability first.
+
+```bash
+atris imessage doctor --json
+```
+
+2. If the doctor says permissions are missing, ask the user to grant Full Disk Access to the terminal or Atris Desktop.
+
+3. Read context only when needed.
+
+```bash
+atris imessage recent "+15555555555" --limit 20
+```
+
+4. Never send a message unless the user approved the exact recipient and exact text.
+
+5. For sending, use the project-approved local iMessage path only after explicit approval.
+
+## Status Meaning
+
+- `connected: true` means this Mac can access the local Messages database and local scripting tools.
+- `connected: false` means the user needs macOS permissions, Messages setup, or local tooling.
+
+## Boundaries
+
+- Do not route iMessage setup through Google OAuth.
+- Do not treat iMessage as a cloud credential.
+- Do not upload message contents unless the user explicitly asks.