@lotics/cli 0.136.1 → 0.143.0

package/AGENTS.md

@@ -2,12 +2,15 @@
 
 The model an agent needs before driving this CLI: which surface answers which question, what the
 conventions are, and where the traps are. It deliberately does **not** list commands — `lotics --help`
-is generated from the code and is the only always-current inventory.
+renders § COMMANDS from the same table the CLI dispatches on, so it is the one inventory that cannot
+fall behind the binary you have.
 
 | Read | For |
 |---|---|
 | `lotics --help` | The verb inventory (§ COMMANDS) and global flags. Authoritative; never stale. |
 | `lotics tools` · `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |
+| `lotics docs` · `lotics docs <area>` | Every reference the packages installed beside the project actually ship — `@lotics/app-sdk`, `@lotics/ui` and the document engines each carry their own, and this index only covers THIS package. Discovered by looking, not by a list, so it reports the installed VERSION of each: a doc always describes the code that is really there. |
+| [docs/building_an_app.md](./docs/building_an_app.md) | The SEQUENCE — scaffold, model, types, queries, workflows, screens, ship — and the deploy-free inner loop. The other references describe contracts; this one is the order they go in and why. Read it once before starting an app. |
 | [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas — the detail `--help` compresses. Read it before hand-building a `set_app_*` payload: several tools REPLACE rather than patch, and a CLI verb already owns the safe assembly. |
 | [docs/document_templates.md](./docs/document_templates.md) | Generating PDF/Excel/Word/email from reusable templates. |
 | [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the workspace facts an agent can't guess; access-vs-activation; catalog-then-stage retrieval. |
@@ -48,6 +51,18 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   `workspace doctor` on findings. Scripts can gate on them.
 - **Text output is the default and is built for reading**; reach for `--json` only when a field is
   needed programmatically.
+- **`lotics report '<json>'` is the channel for what nothing else records.** Telemetry is keyed off
+  commands that FAILED, so the two classes worth the most are invisible to it: a capability that
+  does not exist (no command ran) and a run that exited 0 having done the wrong thing. Reach for it
+  when the platform is genuinely missing something, when a success was wrong, or when an error did
+  not name the remedy — not for your own mistakes, which the logs already show.
+  **It is a frame, not a paragraph** — `{goal, actual, expected?, tried?, wanted?}`, because a log
+  reconstructs what you RAN and never what you WANTED, and that gap is the report. `goal` and
+  `actual` are required; there is no severity or category to pick (how bad and how common are read
+  off the corpus, and a taxonomy in a released binary cannot be corrected without a release). The
+  session's commands attach themselves — do not retype them. Run it bare for the full prompt; a
+  long one rides `@file.json` or an explicit `-` for stdin (bare NEVER reads stdin, so an
+  inherited pipe cannot wedge the one command meant to unblock you).
 - **`LOTICS_TELEMETRY=1` correlates a whole session** so the authoring loop's rough edges can be
   found and fixed. Off by default; set it in the shell profile, not per command (each invocation is
   its own process). It sends no arguments, no file contents, and no record data — see README
@@ -78,3 +93,7 @@ whether something exists, read `lotics --help` § COMMANDS — the whole section
   `src/agents/<alias>.md` and is pushed by `app agent set`.
 - **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.
 - **Anything needing a browser.** `app dev` and `file preview` shell out to a local Chrome.
+
+Everything above is a *known* boundary. When you hit one that is NOT listed here — a verb that
+should exist and does not — that is the gap worth reporting, and `lotics report` is how it reaches
+us. Working around it silently is how it stays missing.

package/README.md

@@ -12,6 +12,12 @@ Lotics is an AI-powered operations platform. Through this CLI you can:
 
 ## Capability guides
 
+**`lotics docs`** lists every reference the packages installed beside your project ship — each
+`@lotics/*` package carries its own, so a doc always describes the version you actually have.
+`lotics docs <area>` prints one (`lotics docs ai`); `lotics docs ui` prints a package's index.
+Nothing is copied here — the packages, the areas, the titles and the versions are all read at run
+time, so a doc or a whole package added upstream shows up without upgrading this CLI.
+
 **Driving this CLI from an agent? Start at [AGENTS.md](./AGENTS.md)** (`node_modules/@lotics/cli/AGENTS.md`)
 — which surface answers which question, the conventions that hold across every command, and the traps.
 Per-command contracts, flags, exit codes and gotchas are in
@@ -116,6 +122,47 @@ Arguments contribute a **hash** and a **shape** (`records[].data.name:string`) a
 
 Unset, nothing is stored, nothing is sent, and no spool file is created.
 
+### Reporting a problem
+
+```bash
+lotics report '{"goal":"rename a view","actual":"no command does it","wanted":"lotics run update_view"}'
+lotics report @report.json       # a long one, from a file
+cat report.json | lotics report -   # or from stdin — `-` is required, see below
+lotics report                    # the frame, and what is worth reporting
+```
+
+This is the channel for what the records above **cannot** show. Everything they capture hangs off a
+command that failed, which leaves out the two things worth the most: a capability that does not
+exist (no command ran, so nothing was recorded) and a command that exited 0 having done the wrong
+thing. Also worth sending: an error whose message did not tell you how to fix it, and anything that
+made authoring slower than it should have been.
+
+**A report is a frame, not a paragraph.** A log can reconstruct what you *ran*; nothing can
+reconstruct what you *wanted*, and the gap between the two is the report.
+
+| Field | | |
+|---|---|---|
+| `goal` | required | what you were trying to accomplish |
+| `actual` | required | what happened instead |
+| `expected` | | what you expected — the gap between this and `actual` is the defect |
+| `tried` | | what you already tried, and what it said |
+| `wanted` | | what would have unblocked you |
+
+There is no severity or category to pick. How bad and how common are read off the corpus; what you
+were trying to do is not recoverable from anywhere else.
+
+Reading from stdin needs an explicit `-`. `report`'s only argument IS the report, so a bare
+invocation and a piped one look identical in argv — and "is this a pipe?" cannot tell a live
+writer from a descriptor a supervisor left open, so guessing either hangs forever or drops a
+slow writer's report. With `-` the bare form always prints the frame and a piped one waits as
+long as it takes.
+
+If `LOTICS_TELEMETRY=1` is set, the commands from your session attach themselves — don't retype
+them. It runs whether or not telemetry is on (invoking it is the consent that passive recording
+needs an opt-in for), posts immediately, and tells you if it did not land.
+
+Do not paste records, file contents, or credentials.
+
 In an app project, `lotics app *` commands derive the credential from the directory when nothing explicit chose one: the manifest names the app's workspace, and when exactly one saved profile owns that workspace, that profile is used — the machine-wide default (which another shell can move between two of your commands) is never consulted. An explicit flag, env var, or directory pin still wins, and an org whose profile remembers a different workspace simply falls through to the announced default, exactly as before.
 
 ## Workspaces