@lotics/cli 0.143.2 → 0.144.0

package/AGENTS.md

@@ -1,9 +1,7 @@
 # @lotics/cli — agent index
 
 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`
-renders § COMMANDS from the same table the CLI dispatches on, so it is the one inventory that cannot
-fall behind the binary you have.
+conventions are, and where the traps are.
 
 | Read | For |
 |---|---|
@@ -51,18 +49,15 @@ 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
+- **`lotics report '<json>'` is the channel for what nothing else records.** Reach for it
+  when the platform is genuinely missing something (a capability that does not exist — no
+  command ran), when a success was wrong (exited 0, wrong effect), 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
+  `actual` are required; there is no severity or category to pick. 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).
+  long one rides `@file.json` or an explicit `-` for stdin (bare NEVER reads stdin).
 - **`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
@@ -93,7 +88,3 @@ 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

@@ -23,9 +23,12 @@ time, so a doc or a whole package added upstream shows up without upgrading this
 Per-command contracts, flags, exit codes and gotchas are in
 [docs/cli_reference.md](./docs/cli_reference.md); `lotics --help` is the always-current verb list.
 
-Two of the platform's primary surfaces have dedicated usage guides that ship inside this
+The platform's primary surfaces have dedicated usage guides that ship inside this
 package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
 
+- [`docs/building_an_app.md`](docs/building_an_app.md) — building a custom-code app end to end:
+  the sequence the steps go in (clarify → model → types → queries → workflows → screens → ship)
+  and the deploy-free inner loop. Read it once before starting an app.
 - [`docs/document_templates.md`](docs/document_templates.md) — generate finished documents
   (PDF, Excel, Word, email) by filling reusable templates: the five template types, the
   create → generate → chain lifecycle, and the marker capabilities.
@@ -33,8 +36,6 @@ package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
   workspace facts an agent can't guess, the access-vs-activation model, and the
   catalog-then-stage retrieval model agents use to pull only the lines they need.
 
-Both point to `lotics tools <name>` for exact input schemas.
-
 ## Install
 
 ```bash
@@ -118,7 +119,7 @@ Every request identifies the CLI (`user-agent: lotics-cli/<version> node/<v> <pl
 - Requests carry a session id shared by every command in the sitting — under an agent harness it adopts the harness's own session id, otherwise it rolls over after 30 minutes idle (`~/.lotics/session.json`).
 - Each invocation appends one record to `~/.lotics/telemetry.ndjson` — the command, its exit code, how long it took, and, on a failure, the message that was printed. Batches are sent on a later run; a failed send is retried, never dropped silently.
 
-Arguments contribute a **hash** and a **shape** (`records[].data.name:string`) and nothing else — no values, no file contents, no record data. The hash is the point: two failures in a row with the same hash mean the error message did not tell you enough to fix the call, which is how bad errors get found. This turns "this command failed" into "this command failed after these eleven, and the agent never recovered."
+Arguments contribute a **hash** and a **shape** (`records[].data.name:string`) and nothing else — no values, no file contents, no record data. The hash is the point: two failures in a row with the same hash mean the error message did not tell you enough to fix the call.
 
 Unset, nothing is stored, nothing is sent, and no spool file is created.
 
@@ -148,14 +149,10 @@ reconstruct what you *wanted*, and the gap between the two is the report.
 | `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.
+There is no severity or category to pick.
 
-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.
+Reading from stdin needs an explicit `-`. 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
@@ -163,7 +160,7 @@ 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.
+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 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.
 
 ## Workspaces
 
@@ -313,7 +310,6 @@ cat input.json | lotics app agent run app_abc recognize        # inputs via stdi
 lotics app agent run app_abc recognize --json                  # full run summary to stdout
 lotics app agent run app_abc recognize --session cli-123 '{}'  # continue an existing thread
 
-# Dev-link @lotics/ui to packages/ui/src for live HMR (Vite alias; deploy bundles it)
 # Dev-link @lotics/ui to a monorepo checkout for ONE command — nothing is written to disk
 LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app dev
 LOTICS_UI_SRC=/abs/monorepo/packages/ui/src lotics app deploy -m "..."   # warns: bundles YOUR kit copy