Finalize inbox artifacts and error protocol

docs/implementation-roadmap.md

@@ -18,8 +18,8 @@ As of now:
 - `inbox` and `orch` both compile
 - shared SQLite schema initialization exists
 - `inbox` is implemented end-to-end, including send/fetch/claim/renew/update/reply/done/fail/cancel/list/show/watch/wait-reply
-- `inbox` supports blocking waits, lease renewal, unread fetches, and `--body-file`
-- integration tests cover the main inbox lifecycle plus wait/watch flows
+- `inbox` supports blocking waits, lease renewal, unread fetches, `--body-file`, artifact attachments, and structured JSON errors with stable exit codes
+- integration tests cover the main inbox lifecycle, wait/watch flows, artifact persistence, and JSON error contracts
 - `orch` currently exists as a command skeleton only
 - no scheduler workflows have been implemented yet
 

docs/inbox-cli.md

@@ -146,6 +146,9 @@ Suggested flags:
 - `--body-file PATH`
 - `--payload-json STRING`
 - `--priority low|normal|high`
+- `--artifact PATH`
+- `--artifact-kind KIND`
+- `--artifact-metadata-json STRING`
 
 ### `inbox fetch`
 
@@ -191,6 +194,9 @@ Suggested flags:
 - `--body TEXT`
 - `--body-file PATH`
 - `--payload-json STRING`
+- `--artifact PATH`
+- `--artifact-kind KIND`
+- `--artifact-metadata-json STRING`
 
 ### `inbox reply`
 
@@ -206,6 +212,9 @@ Suggested flags:
 - `--body TEXT`
 - `--body-file PATH`
 - `--payload-json STRING`
+- `--artifact PATH`
+- `--artifact-kind KIND`
+- `--artifact-metadata-json STRING`
 
 ### `inbox done`
 
@@ -219,6 +228,9 @@ Suggested flags:
 - `--body TEXT`
 - `--body-file PATH`
 - `--payload-json STRING`
+- `--artifact PATH`
+- `--artifact-kind KIND`
+- `--artifact-metadata-json STRING`
 
 ### `inbox fail`
 
@@ -231,6 +243,9 @@ Suggested flags:
 - `--summary TEXT`
 - `--body TEXT`
 - `--payload-json STRING`
+- `--artifact PATH`
+- `--artifact-kind KIND`
+- `--artifact-metadata-json STRING`
 
 ### `inbox cancel`
 
@@ -241,6 +256,9 @@ Suggested flags:
 - `--agent AGENT`
 - `--thread THREAD_ID`
 - `--reason TEXT`
+- `--artifact PATH`
+- `--artifact-kind KIND`
+- `--artifact-metadata-json STRING`
 
 ### `inbox list`
 
@@ -263,6 +281,8 @@ Suggested flags:
 - `--thread THREAD_ID`
 - `--json`
 
+`show` should include per-message artifact references when present.
+
 ### `inbox watch`
 
 Block until new matching activity appears.