qriton 0.4.1 → 0.5.0

package/README.md

@@ -1,20 +1,18 @@
 # Qriton CLI
 
-A coding agent for your terminal that runs on infrastructure you control. Use a local model on your own machine, or any major model API, in the same session: your conversation, approvals and project memory stay with the work when you switch models.
-
-It is also home to **[Qriton HLM](https://hlm.qriton.com/)**, our own open models: run them on your machine and teach them, correct them or make them forget, with every change checked and reversible.
+A coding agent for your terminal and paired iPhone, running on infrastructure you control. Use a local model on your own machine, or any major model API, in the same session: your conversation, approvals and project memory stay with the work when you switch models.
 
+Use **[Qriton HLM](https://hlm.qriton.com/)** to work with Qriton's published models in the same project: set up a Python runtime, download verified weights, edit runner code, and inspect saved results.
 ```bash
 npm install -g qriton
 ```
 
-## What's new in 0.4
+## What's new in 0.5.0
 
-- **Windows.** Runs natively on Windows, using PowerShell 7 or `cmd.exe`.
-- **A backup plan for your model.** A dropped connection or overloaded service is retried by itself, and you can list backup models to switch to, with or without asking first. [More](#choose-a-model)
-- **Checked changes.** After editing, the model is asked to test its change before it says it is done.
-- **Several qritons, one team.** Qriton instances on different machines can see each other and pass messages, end-to-end encrypted, over your local network or an internet relay. [More](#several-qritons-on-one-network)
-- **Safer by default.** Stricter rules for which commands run without asking, and a clearer approval for each one.
+- **Guided HLM setup.** Preview and install a Python runtime and starter project for supported HLM5 models.
+- **Editable model projects.** Work on runner code, execute registered commands, and review saved outputs from the CLI or coding assistant.
+- **HLM facts in coding tasks.** Discover saved facts and verify their current answers with local model inference.
+- **Clearer recovery.** File tools provide guidance for recoverable path mistakes, and transient Ollama failures use the configured retry policy.
 
 ## Get started
 
@@ -43,38 +41,96 @@ On a smaller machine, `qriton --light` runs a lighter session: a smaller context
 
 ## Qriton HLM
 
-HLM is Qriton's own family of open language models, and qriton is where you work with them. Run an HLM model locally, then change what it knows: teach it a fact, correct one, or make it forget. The model's weights never change. Each edit is a small, separate memory that you preview before it applies: qriton shows the model's real answer before and after, checks that other facts and unrelated prompts are unaffected, and refuses edits that fail. Any edit can be undone exactly.
+Create a workspace for a supported HLM5 model. Guided setup requires Python
+3.10–3.12; model weights are downloaded separately from Hugging Face.
 
 ```bash
-qriton hlm catalog                                    # the HLM models available
-qriton hlm fetch hlm5-1b                              # download and verify (about 4.2 GB)
-qriton hlm predict hlm5-1b "The capital of France is"
+mkdir my-hlm-project
+cd my-hlm-project
+qriton hlm setup                         # list supported models
+qriton hlm setup hlm5-1b                 # preview runtime and project setup
 ```
 
-An edit is one line in a small file:
+Review the plan, then copy its printed apply command, including the fingerprint:
 
 ```text
-memorize "The capital of Veldoria is" " Paris"
+qriton hlm setup hlm5-1b apply <fingerprint>
 ```
 
+Download the model and run it:
+
 ```bash
-qriton hlm preview hlm5-1b edit.hlm controls.json     # check it before anything changes
-qriton hlm apply <proposal-id>                        # use it
-qriton hlm compare hlm5-1b "The capital of Veldoria is"   # original model versus your edits
-qriton hlm restore <proposal-id>                      # go back exactly
+qriton hlm fetch hlm5-1b
+qriton hlm doctor
+qriton hlm run hlm5-1b -- --prompt "Once upon a time" --tokens 16
+qriton hlm runs
 ```
 
-| Model | Size | |
-|---|---|---|
-| `hlm5-1b` | 4.2 GB | run and edit |
-| `hlm5-1b-hybrid` | 4.2 GB | run and edit, with a trained memory component |
-| `hlm5-3b` | 10.8 GB | run |
+Setup creates an environment and editable Python code inside your workspace.
+Open Qriton there and ask it to inspect or change
+`.qriton/hlm/project/model/run.py`, run the model, and review its output.
+Start a new coding session after setup to load the updated settings.
+The guided runtime uses CPU inference. See the [setup guide](docs/hlm-setup.md)
+for interpreter selection, disk requirements, and supported platforms.
+
+| Model | Download size | Workbench support |
+|---|---:|---|
+| `hlm5-1b` | 4.2 GB | Completion and memory edits |
+| `hlm5-1b-hybrid` | 4.2 GB | Completion and memory edits |
+| `hlm5-3b` | 10.8 GB | Completion |
+
+**Existing projects.** Select a compatible registry with `hlm.projectRegistry`
+in user configuration, then run Qriton in that model workspace:
+
+```text
+qriton hlm projects                      # browse registered projects
+qriton hlm project <id>                  # inspect a runner and required files
+qriton hlm run <id>                      # execute its registered command
+qriton hlm runs                          # review saved outcomes
+```
+
+The coding assistant can inspect and edit these projects and request approval
+to run their commands. Other architectures and custom checkpoints need their
+own loaders and registered runners. See [existing model projects](docs/hlm.md#work-with-existing-model-projects).
+
+**Editable memory.** The 1B models support checked, reversible single-token
+answers at exact prompts, with up to 32 fact addresses per overlay. Base weights
+stay frozen. Preview checks the proposed answer, retained facts, and control
+prompts before an edit can be applied. These checks do not establish general
+learning or accuracy on paraphrased questions. Forgetting deactivates an edit
+and retains its history.
+
+```text
+memorize "The capital of Veldoria is" " Paris"
+```
+
+Save that line as `edit.hlm`, provide a control suite, then use:
+
+```text
+qriton hlm preview hlm5-1b edit.hlm controls.json
+qriton hlm apply <proposal-id>
+qriton hlm facts hlm5-1b
+qriton hlm read hlm5-1b <fact-id> <revision>
+qriton hlm restore <proposal-id>
+```
+
+See the [HLM guide](docs/hlm.md) for control examples, corrections, restoration,
+and [using facts in conversation](docs/hlm.md#manage-an-hlm-fact-through-conversation).
+HLM supplies a separate model workbench; your selected coding provider still
+handles the conversation and code changes. Saved fact routing and fresh native
+model reads are separate operations.
 
-Learn more at [hlm.qriton.com](https://hlm.qriton.com/); the models are on [Hugging Face](https://huggingface.co/qriton). HLM runs in Python, separately from the coding assistant: run `qriton hlm` for setup and `qriton hlm doctor` to check it. The same commands work inside a session after `/hlm`. For HLM3 checkpoints, `qriton energy` offers the same preview, apply and restore workflow in Energy Language.
+These commands also work after `/hlm` in terminal or paired-phone chat.
+On a `qriton serve` host, the models and Python runtime stay on the host; the
+phone provides the conversation and approvals. See the
+[phone workflow](docs/hlm.md#use-hlm-from-your-iphone).
+Published models are available on [Hugging Face](https://huggingface.co/qriton).
 
 ## What stays on your machine
 
-With a local model, your prompts and the files Qriton reads never leave your computer. When you pick a hosted model (Claude, OpenAI, Grok), the conversation and the files it reads are sent to that provider. API keys are stored in the macOS Keychain, libsecret on Linux, or a private file, never in your project or configuration.
+Running Ollama on this computer keeps chat inference local. A remote Ollama server or hosted model receives the conversation and selected code context; search, embedding, mesh and mobile services also have their own destinations. Choosing a local chat model alone does not disable those services. API keys are stored in the macOS Keychain, libsecret on Linux, or a private file, never in your project or configuration.
+
+For a paired phone with a configured gateway, pushes contain generic status such as "Approval waiting" by default, plus session/approval identifiers. Setting `"mobile": { "preview": true }` in user configuration opts into content previews, which travel through the gateway and Apple's push service (APNs). Push requests obey Qriton's HTTP network policy. They are separate from the encrypted mesh messages.
 
 Qriton's file tools only work inside the project folder you started it in. Commands run only as your approval mode allows, and a command you approve runs with your own permissions, so read it before you say yes. Simple reads inside the project run without asking.
 
@@ -121,6 +177,32 @@ qriton --image screenshot.png "what is wrong here"
 
 While Qriton works you can type an addition or correction and press Enter; it joins the task at the next safe step. `Esc` interrupts. `Ctrl+C` twice or `/exit` quits.
 
+### Code from your iPhone
+
+After configuring the [mesh](#several-qritons-on-one-network) and pairing the Qriton iPhone app with `qriton mesh pair`, leave a host running in the project you want to work on:
+
+```bash
+qriton -C ~/code/your-project serve
+```
+
+Open that host in the app, send a coding task and review its proposed changes and command approvals. The work runs on the host with its configured coding model and workspace tools. Use `/project` to see current changes and previous work, then choose a conversation to resume. Use **Stop** to interrupt an active task or workbench command.
+
+Type `/hlm` to inspect and use the host's Qriton models alongside that coding workflow. Model files, input files and Python runtimes live on the host; the phone supplies the conversation, choices and approvals. These slash commands are available on a `qriton serve` host; a terminal session shared with `/share` has a different command interface.
+
+### Pick up unfinished work
+
+Run this in your project when you return to it:
+
+```bash
+qriton project             # current Git changes, recent tasks and last recorded checks
+qriton resume <session-id> # use an id from the overview to continue that conversation
+qriton project json        # the same overview as structured data
+```
+
+The overview runs offline without loading a model or requesting credentials. It reads sessions for this workspace and reports missing Git or session history directly. Older conversations without a saved outcome show that the outcome is unknown. Recorded checks describe that earlier turn; they do not certify the files currently on disk.
+
+Inside a session, use `/project`, then `/resume <session-id>`. The same commands work from a paired phone connected to a serving host; its overview offers resume choices. Resuming opens the conversation so you can continue the work under your current approvals.
+
 ### Approval modes
 
 | Mode | File changes | Commands |
@@ -136,18 +218,25 @@ At an approval: `y` approves once, `n` rejects, `a` always allows what the promp
 
 For `-p` runs nobody is there to approve, so actions that would need approval are rejected. Use `--mode auto-edit` to allow file edits, or `--mode full-auto` for unattended commands.
 
+For changes made through file tools, the completion report records recognized check commands after the latest edit. `passed` means those commands exited zero; it does not assess test coverage or prove the change correct. Failed checks are reported, and another edit clears the earlier check results. Unrecognized commands and changes with no checks remain `unverified`; documentation-only edits do not trigger a test reminder.
+
 ## Memory
 
 Qriton keeps a memory of your project across sessions: conventions, decisions, facts that were hard to find. Ask it to remember something, or use `/remember`. Corrections keep the earlier wording, and forgotten facts can be restored.
 
+When a proposed fact matches an existing memory, automatic capture keeps the existing wording if it differs. Agent `remember` calls also preserve matched user-supplied, pinned or higher-confidence facts; explicit corrections use `update_memory` under the current approval mode. Agent corrections record the agent as their source. Matching does not detect every contradiction, so review important memories. Forgetting retains history for restoration and is not secure deletion.
+
 ```text
 /remember prices are integer euro cents, never floats
 /memory              what is stored, recent entries
 /recall <query>      search memory
 /forget <id>         drop a memory (/restore <id> brings it back)
+/graph               see your project memory as an interactive graph
 ```
 
-Memory is kept per project and stays on your machine. With the embedding model installed (`qriton pull bge-m3`), recall also finds related facts that use different words.
+`/graph`, or `qriton memory graph` from the shell, opens your project's memory in the browser: what qriton knows, how the pieces connect, what was corrected and when. Select a memory to see its history and connections, or to copy the command that forgets or restores it (`qriton memory forget <id>` works from the shell too). The page itself is a single private file that works offline and cannot change anything. `qriton memory graph json`, `dot` or `mermaid` exports it for other tools.
+
+Memory is stored locally per project. Recalled facts become context for your selected chat model, and semantic recall sends text to the configured embedding service. With the local embedding model installed (`qriton pull bge-m3`), recall also finds related facts that use different words.
 
 ## Commands
 
@@ -158,18 +247,19 @@ Type `/` for suggestions. The most used:
 | `/help` | all commands and shortcuts |
 | `/model <name>`, `/models` | switch or browse models |
 | `/mode <mode>`, `/auto [on\|off]` | change approval mode |
+| `/project` | current changes, recent work and recorded checks |
 | `/sessions`, `/resume [id]` | browse and continue past conversations |
 | `/memory`, `/remember`, `/recall`, `/forget` | project memory |
-| `/hlm` | run and edit Qriton HLM models |
+| `/hlm` | run and edit Qriton HLM models; `/hlm overview` shows local setup and next steps |
 | `/servers`, `/server <url>` | find or select an Ollama server |
 | `/image <path>` | attach a screenshot to your next message |
 | `/compact` | summarise the conversation to free space |
 | `/stats`, `/usage` | speed, context use, token and cost log |
 | `/unload` | free the memory local models are using |
-| `/theme light\|dark` | colours for a light or dark terminal |
+| `/theme auto\|light\|dark` | colours: auto matches your terminal's background |
 | `/clear` | start over |
 
-From the shell: `qriton hlm`, `qriton models`, `qriton sessions`, `qriton usage`, `qriton doctor`, `qriton capabilities`.
+From the shell: `qriton project`, `qriton hlm`, `qriton models`, `qriton sessions`, `qriton usage`, `qriton doctor`, `qriton capabilities`.
 
 ## Configuration
 
@@ -212,10 +302,54 @@ qriton mesh join <code>                    # every other machine
 
 Then set `"mesh": { "enabled": true, "name": "laptop" }` in `~/.qriton/config.json` on each machine. Interactive sessions join the mesh; one-off `-p` runs stay private. In a session, `/peers` shows who is online (machine, project, model, busy or idle, and a fingerprint), `/tell <peer> <text>` sends a message, and `/mesh scan` finds NATS servers on your network. The model can also list peers and send messages; sending asks for approval unless you run in `full-auto`.
 
-**Everything is end-to-end encrypted.** Each machine has its own keys, and every message is encrypted and signed before it leaves, so the NATS server, or anyone on the network, sees only random bytes on random-looking channels. Direct messages can be read by their recipient only, not even by other machines in the group. The invite code contains the group secret, so pass it only over a channel you trust. A relay on the internet also needs `tls://`, and per-machine keys (`qriton mesh status` prints the one to add to the server).
+**Mesh messages are end-to-end encrypted.** Each machine has its own keys, and every mesh message is encrypted and signed before it leaves, so the NATS server, or anyone on the network, sees only random bytes on random-looking channels. Direct messages can be read by their recipient only, not even by other machines in the group. The invite code contains the group secret, so pass it only over a channel you trust. A relay on the internet also needs `tls://`, and per-machine keys (`qriton mesh status` prints the one to add to the server).
 
 A received message is shown to you and waits for `/accept`. With `"accept": "auto"` it joins the task queue on its own, so qritons can coordinate work without you in the loop. Either way it is labelled as coming from another agent, never from you: it grants no permission, and every action still goes through your approvals. The mesh is off unless you configure it, and a project can never turn it on.
 
+Incoming messages also pass through the Shield. You always see every message; the Shield only decides whether it may join the task on its own:
+- **Unflagged messages** behave as described above.
+- **Flagged messages from machines you trust** are never held back. List those machines' ids (shown by `/peers`) in `"trusted"` in your user config, and the warning travels with the message to you and to the agent. The one exception is a possible credential: it waits for `/accept`, so a secret never reaches a model without you choosing it.
+- **Flagged messages from any other member** never join by themselves. They wait for `/accept`, or cannot be accepted at all in Shield `block` mode or when they contain a possible credential.
+
+Trust is the machine's id, which each message proves with its signature, so a message cannot borrow a trusted machine's name.
+
+Pattern checks can be fooled, so they are not the last line of defence. Once a message from another qriton joins a conversation, trusted or not, that conversation holds **outside input**, and the status line says so:
+- **Every action asks you:** writes, commands, commits, memory changes and mesh sends, in any approval mode including `full-auto`.
+- **Network tools ask too:** web search, fetch and research could carry data out in their arguments, so they ask as well.
+- **No session-wide approvals:** "allow for this session" is not offered, and earlier grants do not apply.
+- **Local reading and thinking stay free:** the agent can still read files, reason and draft on its own.
+
+A model that is talked into something by that text still cannot act on it without you. The mark lasts until `/clear`, because the text stays in the model's context, and a resumed conversation containing such a message is marked again.
+
+## A signed agent on the web
+
+Websites are starting to tell known agents from anonymous bots. With Web Bot Auth, the IETF draft that Cloudflare, Google and others are testing, qriton can sign its page fetches (`fetch_url`, `research`). A site can then recognise this agent and apply its own policy, instead of blocking it or treating it as a scraper posing as a browser.
+
+```sh
+qriton agent                          # this agent's key id, and whether signing is on
+qriton agent directory ./site         # the public key, ready to host
+qriton agent check                    # a signed request to Cloudflare's test endpoint, explained
+```
+
+To turn it on:
+1. Host the key directory at an https address you control, at `https://agent.example.com/.well-known/http-message-signatures-directory`. `qriton agent directory` writes it, with a `web.config` for IIS.
+2. Set this in `~/.qriton/config.json`, listing the sites that should know who you are:
+   ```json
+   { "webAgent": { "sign": true, "directory": "https://agent.example.com", "sites": ["shop.example", "*.gov.example"] } }
+   ```
+
+Page fetches to those sites, over https only, then carry an Ed25519 signature over the target host, valid for one minute, plus a `Signature-Agent` header pointing at your directory. They identify as `qriton/<version> (+https://agent.example.com)`.
+
+Every other site sees an anonymous browser request, exactly as before. A redirect is decided again for each site it passes through, and a signature never travels on to a site that is not listed. `"*"` signs everywhere, but only if you write it.
+
+Identifying as an agent also tells a site it may serve you a page written for agents, with hidden instructions. So a page fetched while identified counts as outside input: until `/clear`, every action in that conversation asks you first. One key can serve several machines: copy `~/.qriton/web-agent.json` between them, so sites cannot tell the machines apart.
+
+- **The key:** it belongs to this installation. It is kept privately in `~/.qriton/web-agent.json`, separate from mesh keys; only the public half is published.
+- **Off by default,** and even when on, it only signs for the sites you list.
+- **User settings only:** a project cannot change it.
+- **Standard format:** signatures match the RFC 9421 and draft test vectors, and Cloudflare's test endpoint accepts them as well-formed.
+- **Recognition:** sites recognise the key once the directory is published, and for Cloudflare, once the agent is registered.
+
 ## Teams and managed machines
 
 Administrators can restrict network destinations, allowed approval modes and which project settings apply, and can run commands in a network-isolated container. For the deployment guide, write to **cli@qriton.com**.