@giovannijecha/jecode 0.7.0 → 0.7.2

package/README.md

@@ -9,8 +9,8 @@
 <p align="center"><strong>Your code. Your loop.</strong></p>
 
 <p align="center">
-  A focused coding agent that lives in your terminal, keeps tool use visible,
-  and stays under your control.
+  A focused terminal coding agent with visible tool use, durable sessions, and
+  one controller that stays under your control.
 </p>
 
 <p align="center">
@@ -21,367 +21,346 @@
 </p>
 
 <p align="center">
-  <a href="https://github.com/giovannijecha/jecode/blob/main/CHANGELOG.md">Changelog</a> ·
+  <a href="https://github.com/giovannijecha/jecode/blob/main/CHANGELOG.md">Changelog</a> &middot;
   <a href="https://github.com/giovannijecha/jecode/releases">Releases</a>
 </p>
 
-> Jecode is an early 0.7.x release. The core loop is usable today; commands and
+> Jecode is currently pre-1.0. The core loop is usable today, but commands and
 > terminal interactions may still evolve before 1.0.
 
 ## Why Jecode
 
-- **One controller.** One visible loop talks to the model, runs tools, and returns
-  control to you. Independent reads can overlap inside one step; writes and
-  commands remain ordered. There are no hidden workers or delegated agents.
-- **Terminal-native.** The transcript, composer, searchable menus, tool output,
-  diffs, approvals, reasoning, and status all share one full-screen TUI.
-- **Permission-aware.** Reads stay transparent; dangerous actions ask first.
-  Session approvals can be reviewed and revoked.
-- **Durable by default.** Interactive conversations survive terminal exits and
-  can be resumed without replaying tools. Batch runs remain stateless.
-- **Context-bounded.** Older model context is summarized automatically while
-  the complete conversation and transcript remain available in the session.
-- **Provider-neutral.** Use Anthropic or OpenAI API keys, a ChatGPT account, or
-  a local/remote Ollama server without changing the workflow.
-- **Lean by construction.** Jecode installs as plain JavaScript, runs on
-  Node.js 22.18+ (22.x) or Node.js 24+, executes no installation scripts, and
-  has zero third-party runtime dependencies.
-
-## Install
-
-Jecode requires **Node.js 22.18+ on the 22.x line, or Node.js 24+**, and npm:
-
-~~~console
+- **One visible loop.** One controller talks to the model, runs tools, and
+  returns control to you. Independent reads may overlap inside a step; writes
+  and commands stay ordered. There are no delegated agents or hidden model
+  workers.
+- **Terminal-native today.** The transcript, composer, searchable menus, tool
+  output, diffs, approvals, reasoning, and status share one full-screen TUI.
+- **Permission-aware.** Tool use is visible. Dangerous actions ask first, and
+  remembered session approvals can be reviewed or revoked.
+- **Durable and context-bounded.** Interactive conversations survive terminal
+  exits. Older model context can be compacted while the complete conversation
+  and transcript remain available in the saved session.
+- **Multi-provider.** Use Anthropic or OpenAI API keys, an eligible ChatGPT
+  account, or a local, cloud, or remote Ollama server without changing the
+  workflow.
+- **Lean by construction.** Jecode ships as owned JavaScript built on Node.js
+  primitives, executes no installation scripts, and has zero third-party
+  runtime dependencies. This is a permanent product constraint, not a temporary
+  optimization.
+
+## Quick start
+
+Jecode requires **Node.js 22.18+ on the 22.x line, or Node.js 24+**, and npm.
+
+```console
 npm install --global @giovannijecha/jecode
 jecode --version
-~~~
+cd path/to/your/project
+jecode
+```
 
-To try prereleases instead, install the opt-in **next** channel with
-`npm install --global @giovannijecha/jecode@next`.
+Jecode opens directly on an empty composer. Use `/providers` to connect a
+service, `/models` to choose a model, then describe the work you want done.
 
-Published npm packages are the supported installation artifacts. Git URL
-installs are intentionally unsupported: the source tree contains no generated
-runtime and defines no install-time build hook.
+```text
+Review this project, explain its architecture, and propose the smallest safe
+change to improve startup performance.
+```
 
-Then open the project you want to work on and run Jecode:
+Use `jecode --root path/to/project` to select another workspace, or
+`jecode --ephemeral` when the conversation must stay memory-only.
 
-~~~console
-cd path/to/your/project
-jecode
-~~~
+Resume a saved conversation for the current workspace with a searchable picker:
 
-Resume a saved conversation for the current project with a searchable picker,
-or open the most recent one directly:
-
-~~~console
+```console
 jecode resume
 jecode resume --latest
-~~~
+```
 
-Use `jecode --ephemeral` when a conversation must stay memory-only.
+Run `jecode --help` for every startup option. Windows, Ubuntu, and macOS are
+covered by the project test matrix.
 
-You can point at another workspace explicitly:
+### Prereleases
 
-~~~console
-jecode --root path/to/your/project
-~~~
+The stable npm package is the supported installation artifact. To try an
+opt-in prerelease:
 
-Run **jecode --help** for all startup options. Tested platforms are Windows,
-Ubuntu, and macOS.
+```console
+npm install --global @giovannijecha/jecode@next
+```
 
-### Update
+Git URL installs are intentionally unsupported: the source tree contains no
+generated runtime and defines no install-time build hook.
 
-Install the current stable release over the existing global command:
+### Update and uninstall
 
-~~~console
+```console
 npm install --global @giovannijecha/jecode
 jecode --version
-~~~
+npm uninstall --global @giovannijecha/jecode
+```
+
+Uninstalling the command preserves `~/.jecode`. Remove that directory only when
+you intentionally want to erase saved settings, credentials, accounts, and
+sessions.
 
-If you installed Jecode from GitHub before the scoped npm package existed,
-remove the old unscoped package once before updating:
+If an older GitHub installation still owns the `jecode` executable, remove the
+legacy unscoped package before installing the scoped package:
 
-~~~console
+```console
 npm uninstall --global jecode
 npm install --global @giovannijecha/jecode
-~~~
+```
 
-An `EEXIST` error for a `bin/jecode` path usually means that this legacy
-executable still owns the command. Remove it instead of installing with
-`--force`.
-
-### Uninstall
-
-~~~console
-npm uninstall --global @giovannijecha/jecode
-~~~
-
-Uninstalling the command preserves **~/.jecode** so saved settings and
-credentials remain available after a reinstall. Remove that directory only
-when you intentionally want to erase Jecode's local data.
+Do not work around the resulting `EEXIST` error with `--force`.
 
 ### Linux and WSL
 
-WSL has its own Node.js installation and `PATH`; the Node.js version installed
+WSL uses its own Node.js installation and `PATH`; the Node.js version installed
 on Windows does not apply inside it. Keep user-installed npm commands in the
-Linux user path and put that path before inherited Windows entries:
+Linux user path:
 
-~~~console
+```console
 npm config set prefix "$HOME/.local"
 export PATH="$HOME/.local/bin:$PATH"
 npm install --global @giovannijecha/jecode
 hash -r
 command -v jecode
 jecode --version
-~~~
+```
 
 Persist the `PATH` export in `~/.profile` or your shell's startup file. Inside
-WSL, **command -v jecode** should resolve below `/home/...`, not below
-`/mnt/c/.../Volta`. Do not ignore an `EBADENGINE` warning: **node --version**
-must report 22.18+ on the 22.x line, or 24+.
+WSL, `command -v jecode` should resolve below `/home/...`, not through an
+inherited Windows path below `/mnt/c`. Do not ignore `EBADENGINE`: `node
+--version` must report 22.18+ on the 22.x line, or 24+.
 
-### Build from source
-
-~~~console
-git clone https://github.com/giovannijecha/jecode.git
-cd jecode
-npm ci --ignore-scripts
-npm run build:release
-npm link
-jecode
-~~~
-
-Development runs TypeScript directly with **npm run start**. **dist/** is an
-ignored, generated tree used only by linked commands and release tarballs.
-**npm run pack:release** rebuilds it from a clean target before packing; the
-trusted publish workflow performs the same explicit build. Installing the
-published package runs no compilation or installation scripts.
-
-## First session
-
-Jecode opens on an empty composer instead of forcing a setup wizard. Type
-**/providers** to connect the services you use, then **/models** to choose from
-their combined live catalogues. **/settings** keeps the selected model and the
-remaining non-secret defaults together. An API key can remain in memory for
-the current session or be saved explicitly under **~/.jecode**; it is never
-stored in the workspace.
+## Providers
 
 | Provider ID | Authentication | Notes |
-|---|---|---|
-| anthropic | ANTHROPIC_API_KEY | Anthropic API |
-| openai | OPENAI_API_KEY | OpenAI API |
-| openai-codex | ChatGPT OAuth | Experimental; uses eligible ChatGPT Codex access |
-| ollama | OLLAMA_API_KEY for Cloud/remote | Cloud with a key, local without one |
-
-Choose **ChatGPT** in **/providers** to sign in on OpenAI's website without
-pasting a key.
-Jecode offers a local browser callback and a device-code flow; WSL and remote
-terminals default to the device code. The connection is saved only after the
-flow completes. Availability and usage limits are determined by the ChatGPT
-account and plan, not by OpenAI API credits. This integration is experimental
-and is not an endorsement of Jecode by OpenAI.
+| --- | --- | --- |
+| `anthropic` | `ANTHROPIC_API_KEY` | Anthropic API |
+| `openai` | `OPENAI_API_KEY` | OpenAI API |
+| `openai-codex` | ChatGPT OAuth | Experimental; uses eligible ChatGPT Codex access |
+| `ollama` | `OLLAMA_API_KEY` for cloud or remote use | Cloud with a key, local without one |
+
+Choose **ChatGPT** in `/providers` to sign in on OpenAI's website without
+pasting a key. Jecode supports a local browser callback and a device-code flow;
+WSL and remote terminals default to the device code. Availability and usage
+limits depend on the ChatGPT account and plan, not on OpenAI API credits. This
+integration is experimental and is not an endorsement of Jecode by OpenAI.
 
 Anthropic remains API-key only. Jecode does not reuse a Claude consumer
 subscription or copy credentials from another client.
 
-Choose **Ollama** in **/providers** to manage its API key and select **cloud**,
-**local**, or a custom endpoint. Existing users with an Ollama API key
-automatically use **https://ollama.com**; without a key, Jecode uses the local
-daemon at **http://127.0.0.1:11434**. Remote custom endpoints must use HTTPS.
+For Ollama, `/providers` can select cloud, local, or a custom endpoint. With an
+Ollama API key Jecode defaults to `https://ollama.com`; without one it defaults
+to `http://127.0.0.1:11434`. Remote custom endpoints must use HTTPS.
 
 ## Use the TUI
 
-Type **/** to open searchable command completion inside the composer.
+Type `/` to open searchable command completion inside the composer.
 
 | Command | What it does |
-|---|---|
-| /settings | Manage the selected model, limits, context compaction, effort, motion, and provider access |
-| /effort | Change and save reasoning effort directly |
-| /providers | Manage API keys, ChatGPT sign-in, and Ollama connections |
-| /models | Search models across every available provider and select one |
-| /permissions | Change session tool access inline and review remembered approvals |
-| /new | Close the current conversation, start clean, and reset tool permissions |
-| /timeline | Navigate completed turns and select where the next branch starts |
-| /compact | Compact the active model context immediately |
-| /export | Save a timestamped Markdown transcript in the launch directory |
-| /help | Open a temporary keyboard reference in the composer dock |
-| /exit | Restore the terminal and exit |
+| --- | --- |
+| `/settings` | Manage the selected model and saved non-secret defaults |
+| `/effort` | Change and save reasoning effort directly |
+| `/providers` | Manage provider connections, API keys, ChatGPT sign-in, and Ollama endpoints |
+| `/models` | Search all currently usable provider catalogues and select a model |
+| `/permissions` | Change session tool access and review remembered approvals |
+| `/timeline` | Browse resumable turns and select where the next branch should begin |
+| `/compact` | Compact the current branch context without deleting saved conversation history |
+| `/new` | Start a new conversation and reset session tool permissions |
+| `/export` | Save a timestamped Markdown transcript in the launch directory |
+| `/help` | Open a temporary keyboard reference in the composer dock |
+| `/exit` | Restore the terminal and exit |
 
 Useful controls:
 
-- **Up/Down** moves through command suggestions, menus, and input history.
-- **Left/Right** moves the composer cursor or changes an inline menu value;
+- **Up/Down** moves through suggestions, menus, and input history.
+- **Left/Right** moves the cursor or changes an inline value;
   **Ctrl+Left/Right** moves by word.
-- **Backspace/Delete** removes one character; **Ctrl+Backspace/Delete** removes
-  one word. **Home/End** moves to the start or end of the composer.
+- **Backspace/Delete** removes one character;
+  **Ctrl+Backspace/Delete** removes one word.
+- **Home/End** moves to the beginning or end of the composer.
 - **Tab** completes a slash command without running it; **Enter** sends.
 - **Alt+Enter** inserts a newline.
-- **Esc** closes a menu or interrupts the foreground operation.
+- **Esc** closes the active menu or interrupts foreground work.
 - **Ctrl+C** interrupts, or exits while idle. **Ctrl+D** requests a clean exit.
-- **PageUp/PageDown** and the mouse wheel scroll the transcript without losing
-  the place you are reading.
+- **PageUp/PageDown** and the mouse wheel scroll the transcript.
 - **Ctrl+O** expands or compacts the latest reasoning or tool-detail block.
 
-The one-line footer keeps model, effort, and workspace on the left. While work
-is active, the right edge shows its current state, elapsed time, and interrupt
-hint; readiness guidance and temporary feedback use the same replaceable space
-without polluting the transcript. Slash commands never append content to the
-conversation or its Markdown export; **/help** closes with **Esc**, and token
-accounting remains internal to the active session.
+The footer keeps the active model, effort, and workspace visible. During work,
+it adds the current state, elapsed time, and interrupt hint. Operational
+feedback uses the same replaceable status area instead of adding noise to the
+conversation or its Markdown export.
+
+## Sessions and context
+
+Interactive conversations are stored under `~/.jecode/sessions` and scoped to
+the canonical workspace path. A fresh or `/new` conversation is not added to
+the resume picker until it has a settled turn. Resuming and continuing a
+conversation keeps its durable session identity and updates one picker entry
+instead of creating duplicates.
+
+`/timeline` shows completed, failed, and interrupted turns in the conversation
+tree. Selecting an older turn changes only the in-memory path: it creates and
+saves a branch only after the next real user message. Cancelling the picker or
+exiting before that message leaves the durable head unchanged. A failed turn
+keeps the same partial evidence and outcome in the live transcript, export, and
+resume, while the next model receives a neutral failure boundary instead of
+incomplete streamed text. Historical tools are displayed but never executed.
+If a process stops abruptly inside a tool loop, Jecode resumes from the latest
+safe ancestor and lets the next user turn create a branch. `/export` writes
+only the currently selected path.
 
-## Configuration
+When model-facing context approaches the selected model's usable capacity,
+Jecode asks the provider for a bounded summary of the older prefix and keeps
+recent turns exact. The default trigger is 85% and can be changed from 50% to
+95%. Live provider metadata or Ollama's allocated context determines the budget
+when available; provider safety limits always win.
 
-Startup precedence is: command-line flags, environment variables, saved
-settings, built-in defaults.
+Compaction changes only the projection sent to the model. Complete messages,
+tool evidence, transcript, export, and conversation tree remain intact. The
+branch-local summary anchor is saved with the session so resume does not repeat
+the same compaction. `/compact` requests this process immediately, even below
+the automatic threshold; it leaves very small contexts unchanged. After
+selecting a historical turn, send the first new message before compacting so
+shared history is never rewritten.
 
-| Flag | Environment | Default |
-|---|---|---|
-| --provider | JECODE_PROVIDER | anthropic |
-| --model | JECODE_MODEL | Provider default or interactive selection |
-| --ollama-host | OLLAMA_HOST | Cloud with an Ollama key, local without one |
-| --root | — | Current directory |
-| --effort | JECODE_EFFORT | high |
-| --max-tokens | JECODE_MAX_TOKENS | 64000; not sent by openai-codex |
-| --max-steps | JECODE_MAX_STEPS | 40 |
-| --compaction-percent | JECODE_COMPACTION_PERCENT | 85; accepts 50 through 95 |
-| --reduced-motion | JECODE_REDUCED_MOTION=1 | Off |
-| --auto-approve | JECODE_AUTO_APPROVE=1 | Off |
-| --ephemeral | JECODE_EPHEMERAL=1 | Off |
-
-Persistent preferences live in **~/.jecode/settings.json**. Explicitly saved
-API keys live in **~/.jecode/credentials.json**; the ChatGPT OAuth account lives
-separately in **~/.jecode/accounts.json**. Both secret stores use owner-only
-permissions where the operating system supports them. Environment API keys
-always win. Model selection saves the provider and model as one change; the
-separate startup flags remain available for automation and override that saved
-choice.
-
-Interactive conversations are stored under **~/.jecode/sessions**, scoped to
-the canonical workspace path. A checkpoint contains normalized messages and
-the settled transcript needed to redraw the conversation. It excludes stored
-provider credentials, OAuth tokens, provider-only opaque response data,
-permission choices, draft composer text, transient footer notices, and pending
-tool state. Session
-files use owner-only modes on POSIX; Windows relies on the user-profile ACL.
-`jecode resume` keeps the same durable session identity and advances that
-session's conversation tree, so reopening and continuing a conversation does
-not create duplicate picker entries. `/new` or a fresh launch starts another
-logical session. **/timeline** shows the completed turns in that tree. Selecting
-an earlier turn changes only the visible path; it creates and persists a branch
-only when the next real message is sent. Cancelling the picker or exiting first
-leaves the durable head untouched, and resume returns to the last branch with a
-persisted turn. Historical tools are displayed but never executed. If a crash
-left the newest turn inside a tool loop, the same session resumes from its
-latest completed ancestor and the next turn becomes a branch because
-provider-only continuation data is intentionally not stored. **/export** writes
-only the currently selected path.
+## Batch mode
 
-When the model-facing context approaches the selected model's usable capacity,
-Jecode asks the provider for one bounded summary of its older prefix and keeps
-the recent turn exact. The trigger defaults to 85% and can be changed from 50%
-through 95% in **/settings**. Live provider metadata or Ollama's allocated
-runtime context determines the budget when available; a metadata failure falls
-back safely without blocking the turn. Only the provider projection is
-replaced: complete messages, tool evidence, transcript, and conversation tree
-remain unchanged. The branch-local summary anchor is checkpointed with the
-session, so resume reuses it instead of summarizing the same prefix again. A
-failed or cancelled optional summary leaves the original context intact; a
-definite provider context-limit rejection may trigger one compacted retry.
-Internal summary requests count toward provider usage but never appear in the
-transcript or Markdown export. **/compact** requests the same model-aware,
-branch-local compaction immediately, even below the automatic trigger. Very
-small contexts are left unchanged. After selecting a historical branch point,
-send its first new message before compacting so shared history is never
-rewritten.
-
-Jecode has one interface theme: dark Steel. **NO_COLOR** is supported for
-terminals and pipelines that disable colour.
+When stdin or stdout is not a terminal, Jecode switches to a plain
+line-oriented mode:
 
-## Automation
+```console
+printf "explain this project\n" | jecode --root .
+```
 
-When stdin or stdout is piped, Jecode switches to a plain line-oriented mode:
+Batch conversations are stateless. Dangerous tools remain denied unless
+`--auto-approve` is supplied explicitly. Terminal failures are written to
+stderr and exit non-zero so scripts and CI pipelines can stop reliably.
 
-~~~console
-printf "explain this project\n" | jecode --root .
-~~~
+## Configuration
 
-Batch conversations are never written to the session store.
+Startup precedence is: command-line flags, environment variables, saved
+settings, then built-in defaults.
 
-Dangerous tools stay denied in batch mode unless **--auto-approve** is supplied
-explicitly. A terminal batch failure is written to stderr and exits non-zero,
-so shell pipelines can stop reliably.
+| Flag | Environment | Default |
+| --- | --- | --- |
+| `--provider` | `JECODE_PROVIDER` | `anthropic` |
+| `--model` | `JECODE_MODEL` | Provider default or interactive selection |
+| `--ollama-host` | `OLLAMA_HOST` | Cloud with an Ollama key, local without one |
+| `--root` | - | Current directory |
+| `--effort` | `JECODE_EFFORT` | `high` |
+| `--max-tokens` | `JECODE_MAX_TOKENS` | `64000`; not sent by `openai-codex` |
+| `--max-steps` | `JECODE_MAX_STEPS` | `40` |
+| `--compaction-percent` | `JECODE_COMPACTION_PERCENT` | `85`; accepts `50` through `95` |
+| `--reduced-motion` | `JECODE_REDUCED_MOTION=1` | Off |
+| `--auto-approve` | `JECODE_AUTO_APPROVE=1` | Off |
+| `--ephemeral` | `JECODE_EPHEMERAL=1` | Off |
+
+Non-secret preferences live in `~/.jecode/settings.json`. Explicitly saved API
+keys live in `~/.jecode/credentials.json`, while ChatGPT OAuth accounts live in
+`~/.jecode/accounts.json`. Environment credentials always take precedence.
+Secret stores use owner-only permissions where the operating system supports
+them.
+
+Jecode has one current interface theme, Dark Steel. `NO_COLOR` is supported for
+terminals and pipelines that disable colour.
 
 ## Safety model
 
 Jecode treats model output, workspace content, tool output, and terminal text as
 untrusted data.
 
-- Tool paths are confined to the selected workspace. Writes reject symlink and
-  junction components, then revalidate the boundary during atomic replacement.
-- Dangerous tools ask by default unless explicitly allowed for the session in
-  **/permissions** or the process started with **--auto-approve**.
-- Credential fields are masked and excluded from transcripts. Approved shell
-  commands receive no secret-bearing environment variables; `SSH_AUTH_SOCK`
-  is preserved so Git and SSH can use the user's agent, which means an approved
-  command can request that agent to authenticate. Recognized credential values
-  are redacted before tool output reaches the model, screen, history, or export.
+- Current filesystem tools are confined to the selected workspace. Writes
+  reject symlink and junction components, revalidate boundaries, and use atomic
+  replacement.
+- Dangerous tools ask by default unless explicitly allowed for the session or
+  the process starts with `--auto-approve`.
+- Credential fields are masked and excluded from transcripts. Recognized
+  credential values are redacted before output reaches the model, screen,
+  history, or export.
+- Approved shell commands receive no secret-bearing environment variables.
+  `SSH_AUTH_SOCK` is preserved so Git and SSH can use the user's agent, which
+  means an approved command may ask that agent to authenticate.
 - ChatGPT OAuth uses PKCE and an exact loopback callback or the OpenAI device
-  flow. Refresh-token rotation is serialized across Jecode processes; OAuth
-  tokens are withheld and redacted like API keys.
+  flow. Refresh-token rotation is serialized across Jecode processes.
 - Terminal control characters are neutralized before rendering.
-- Remote Ollama endpoints require HTTPS. Provider HTTP redirects are rejected
-  rather than followed across an implicit trust boundary.
+- Remote Ollama endpoints require HTTPS, and provider redirects are rejected.
 - Provider handshakes and idle response bodies have finite deadlines. Only
   idempotent catalogue reads retry; generation requests are never replayed.
-- Model and filesystem input are bounded before they reach the screen or
-  provider.
-- Durable session files are versioned, size-bounded, atomically checkpointed,
-  and treated as untrusted when loaded. A live lease prevents the same saved
-  session from being resumed by two Jecode processes at once.
+- Model, terminal, and filesystem input are bounded before use.
+- Session files are versioned, symmetrically size-bounded before write and
+  after read, atomically checkpointed, and treated as untrusted when loaded. A
+  live lease prevents concurrent resume.
 
-`run_command` is not an operating-system sandbox: an approved shell command can
-still access files and account resources available to the current user. Review
-commands carefully and reserve **--auto-approve** for controlled environments.
+`run_command` is not an operating-system sandbox. An approved command can still
+access files and account resources available to the current user. Review
+commands carefully and reserve `--auto-approve` for controlled environments.
 
-Please read [SECURITY.md](SECURITY.md) before reporting a vulnerability.
+Read [SECURITY.md](SECURITY.md) before reporting a vulnerability.
 
-## Community
+## Project direction
 
-Jecode is built around people using the product and telling us where the loop
-can improve.
+The terminal is Jecode's current primary interface, not the limit of the
+product. Future interfaces may reuse the same controller, session model, and
+visible control system. Expansion must remain deliberate: no hidden model
+hierarchy, no delegated authority, and no weakening of the zero-dependency
+runtime.
 
-- Ask questions, share workflows, and explore ideas in
-  [GitHub Discussions](https://github.com/giovannijecha/jecode/discussions).
-- Report reproducible bugs and focused feature requests through
-  [GitHub Issues](https://github.com/giovannijecha/jecode/issues).
-- Report security concerns privately through the repository Security tab.
+The single-controller rule limits delegation, not duration or scope. Jecode may
+eventually supervise visible, interruptible processes such as development
+servers, file watchers, and test runners. Those processes remain tools owned by
+the controller; they do not receive independent goals, model loops, or tool
+authority.
 
-Public pull requests are not accepted at this stage; code changes remain a
-maintainer/collaborator workflow. See [CONTRIBUTING.md](CONTRIBUTING.md) for the
-short routing guide and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community
-expectations.
+The selected workspace is the current default filesystem boundary. Any future
+access to additional directories or resources must use explicit, reviewable,
+revocable grants rather than silently widening that boundary.
 
-## Development
+## Build from source
 
-~~~console
+```console
+git clone https://github.com/giovannijecha/jecode.git
+cd jecode
 npm ci --ignore-scripts
-npm run check
-~~~
+npm run build:release
+npm link
+jecode --version
+```
 
-The visual lab exercises the complete production TUI—golden conversation,
-live tool trace, output tails, change-centric diffs, approvals, menus, and
-fields—without a provider, network access, tool execution, or workspace writes:
+Development runs TypeScript directly with `npm run start`. `dist/` is an
+ignored generated tree used only by linked commands and release tarballs.
+`npm run pack:release` rebuilds it from a clean target. Installing the published
+package runs no compilation or installation scripts.
 
-~~~console
-npm run tui:lab
-~~~
+Run the complete project checks with:
 
-For a manual long-session rendering probe, run **npm run bench:transcript**.
+```console
+npm run check
+```
 
-Architecture and security boundaries are documented in
-[docs/architecture.md](docs/architecture.md). Brand assets and usage rules live
+Use `npm run tui:lab` to inspect production TUI components with inert local
+fixtures, and `npm run bench:transcript` for a manual long-session rendering
+probe. Architecture and security boundaries are documented in
+[docs/architecture.md](docs/architecture.md); brand assets and usage rules live
 in [docs/brand.md](docs/brand.md).
 
+## Community
+
+- Ask questions, share workflows, and explore early ideas in
+  [GitHub Discussions](https://github.com/giovannijecha/jecode/discussions).
+- Report reproducible bugs and focused feature requests through
+  [GitHub Issues](https://github.com/giovannijecha/jecode/issues).
+- Report security concerns privately through the repository Security tab.
+
+Public pull requests are not accepted at this stage. Code changes remain a
+maintainer and invited-collaborator workflow. See
+[CONTRIBUTING.md](CONTRIBUTING.md) and
+[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
 ## License
 
 Jecode is available under the [MIT License](LICENSE).