noah-code 0.1.1__tar.gz → 0.2.0__tar.gz

{noah_code-0.1.1 → noah_code-0.2.0}/.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
         run: uv run ruff check src tests
 
       - name: Test
-        run: uv run pytest tests
+        run: uv run pytest tests -W error::pytest.PytestUnraisableExceptionWarning
 
       - name: Build distributions
         run: uv build --out-dir build-dist
@@ -77,7 +77,7 @@ jobs:
         run: uv sync --locked --all-extras --dev
 
       - name: Run tests
-        run: uv run pytest tests
+        run: uv run pytest tests -W error::pytest.PytestUnraisableExceptionWarning
 
       - name: Verify command entry point
         run: uv run noah --version
@@ -88,5 +88,5 @@ jobs:
           UV_TOOL_BIN_DIR: ${{ runner.temp }}/noah-bin
         run: |
           uv build --out-dir smoke-dist
-          uv tool install --managed-python --python 3.12 --no-build --with 'nooa[mcp,tracing]==0.0.8' smoke-dist/*.whl
+          uv tool install --managed-python --python 3.12 --no-build --with 'nooa[mcp,tracing]' smoke-dist/*.whl
           "${UV_TOOL_BIN_DIR}/noah" --version

{noah_code-0.1.1 → noah_code-0.2.0}/.github/workflows/release.yml

@@ -50,7 +50,7 @@ jobs:
       - name: Run release checks
         run: |
           uv run ruff check src tests
-          uv run pytest tests
+          uv run pytest tests -W error::pytest.PytestUnraisableExceptionWarning
           uv lock --check
 
       - name: Build wheel and source distribution
@@ -64,7 +64,7 @@ jobs:
           UV_TOOL_DIR: ${{ runner.temp }}/noah-tools
           UV_TOOL_BIN_DIR: ${{ runner.temp }}/noah-bin
         run: |
-          uv tool install --managed-python --python 3.12 --no-build --with 'nooa[mcp,tracing]==0.0.8' dist/*.whl
+          uv tool install --managed-python --python 3.12 --no-build --with 'nooa[mcp,tracing]' dist/*.whl
           "${UV_TOOL_BIN_DIR}/noah" --version
 
       - name: Upload release distributions

{noah_code-0.1.1 → noah_code-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: noah-code
-Version: 0.1.1
+Version: 0.2.0
 Summary: Noah Code terminal coding agent, built on NVIDIA OO Agents (NOOA)
 Project-URL: Homepage, https://github.com/skundu42/noah-code
 Project-URL: Documentation, https://github.com/skundu42/noah-code#readme
@@ -20,11 +20,13 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development
 Requires-Python: <3.14,>=3.12
 Requires-Dist: click>=8.1.0
+Requires-Dist: keyring>=25.0.0
 Requires-Dist: litellm<1.92.0,>=1.84.0
-Requires-Dist: nooa-cli==0.0.8
-Requires-Dist: nooa==0.0.8
+Requires-Dist: nooa-cli==0.0.9
+Requires-Dist: nooa==0.0.9
 Requires-Dist: packaging>=24.0
 Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: textual>=1.0.0
 Requires-Dist: tomli>=2.0.0; python_version < '3.11'
@@ -33,9 +35,9 @@ Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
 Requires-Dist: pytest>=8.0.0; extra == 'dev'
 Requires-Dist: ruff>=0.8.0; extra == 'dev'
 Provides-Extra: mcp
-Requires-Dist: nooa[mcp]==0.0.8; extra == 'mcp'
+Requires-Dist: nooa[mcp]==0.0.9; extra == 'mcp'
 Provides-Extra: tracing
-Requires-Dist: nooa[tracing]==0.0.8; extra == 'tracing'
+Requires-Dist: nooa[tracing]==0.0.9; extra == 'tracing'
 Provides-Extra: tui
 Requires-Dist: textual>=1.0.0; extra == 'tui'
 Description-Content-Type: text/markdown
@@ -70,8 +72,12 @@ and seccomp support. You also need an LLM provider account such as OpenAI, Anthr
 ## Features
 
 - Read files, search with ripgrep, and inspect Git status, diffs, and history.
-- Edit files with anchored replacements, full rewrites, and concurrent-change detection.
-- Run permission-gated shell commands with timeouts and streamed output.
+- Navigate definitions, implementations, references, symbols, hover types, and diagnostics through
+  lazily launched language servers plus an mtime-cached repository map.
+- Edit files with anchored replacements or atomic multi-file patches with exact preimages,
+  rollback, immediate diagnostics, and concurrent-change detection.
+- Run permission-gated shell commands with timeouts and streamed output, or own long-running
+  servers and watchers as bounded background jobs with cursor-based logs.
 - Follow repository instructions from `AGENTS.md`, `CLAUDE.md`, and `.noah-code/instructions.md`.
 - Switch between implementation-focused **build** mode and read-only **plan** mode.
 - Approve actions once or for a session with ordered `allow`, `ask`, and `deny` rules.
@@ -79,7 +85,12 @@ and seccomp support. You also need an LLM provider account such as OpenAI, Anthr
 - Work in an adaptive Atom One Dark cockpit, a classic console, or one-shot non-interactive mode.
 - Type `/` for a live-filtering command and configuration reference; press Enter to send.
 - Follow batched live tool output, then inspect compact execution records with `F2`.
+- Review `/diff` in a keyboard-driven staged/worktree ledger with per-file patches, line deltas,
+  validation state, changed symbols, explicit revert, and checkpoint undo.
 - Resume workspace-scoped sessions with todos and automatic context compaction.
+- Keep full oversized tool results privately while sending the model a focused, reopenable preview.
+- Inspect token, prompt-cache, model-wait, and tool-output usage with `/tokens`; switch live
+  `fast`, `balanced`, and `deep` budgets with `/efficiency`.
 - Switch AI models between turns, with optional cross-repository defaults.
 - Extend workflows with slash commands, opt-in skills, MCP servers, model selection, and tracing.
 
@@ -126,21 +137,55 @@ noah --version
 noah doctor .
 noah config show .
 noah update --check
+noah benchmark .
 ```
 
+Bring your own API key from inside the TUI by entering `/model`: choose the provider, paste the
+key into the masked field, choose the model, then select its reasoning effort. Noah saves the key to the operating system's
+credential store when one is available; otherwise it remains available only to that Noah process.
+API-key values are never written to Noah config, repository, or session files.
+
+Environment variables and the CLI remain available for scripts and headless use:
+
+```bash
+export OPENAI_API_KEY="..."        # or ANTHROPIC_API_KEY / OPENROUTER_API_KEY
+noah providers list
+noah providers add openai --model MODEL_NAME
+noah .
+```
+
+For reasoning models, choose `default`, `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
+Provider and model support varies; `default` omits the parameter. You can set it in the guided
+`/model` flow, switch it live with `/reasoning high`, or launch with:
+
+```bash
+uv run noah --model openai/MODEL --reasoning-effort high .
+```
+
+Custom OpenAI-compatible gateways, vLLM, LM Studio, Ollama, Azure OpenAI, Bedrock, Gemini, Groq,
+Mistral, xAI, DeepSeek, Together AI, and Perplexity are also supported. See the
+[provider configuration guide](docs/configuration.md#bring-your-own-api-provider).
+
 The package also installs `noah-code` and `nc` as equivalent entry points. Because `nc` commonly
-refers to netcat, `noah` or `noah-code` is recommended. Keep provider API keys in the environment
-or trusted NOOA user configuration, never in a repository or Noah Code session metadata.
+refers to netcat, `noah` or `noah-code` is recommended. Keep provider API keys in the OS
+credential store or environment, never in a repository or Noah Code session metadata.
 
-Inside a session, `/model MODEL` switches the active model immediately and remembers it when that
-session is resumed. It does not change other sessions. Use `/model --global MODEL` when the new
-model should also become the default for future sessions in every repository.
+Inside a session, bare `/model` opens guided provider, API-key, model, and reasoning setup. `/model MODEL`
+switches the active model immediately and remembers it when that session is resumed. It does not
+change other sessions. Use `/model --global MODEL` when the new model should also become the
+default for future sessions in every repository.
 
 The TUI keeps the conversation central and adds a session-and-plan rail on terminals at least
 110 columns wide. Tool output streams in a bounded activity panel and compacts after completion,
 keeping long runs responsive without deleting persisted session data. Press `F2` for activity
 details or `F3` for paginated conversation history.
 
+The default `fast` profile uses compact NOOA trajectory rendering, bounded tool results, batched
+repository inspection, cache-friendly turn-boundary context refresh, and lazy MCP connections. A
+configured `lightweight_model` handles coding-session compaction; deterministic titles avoid an
+otherwise unnecessary model request. Run `noah benchmark .` for the deterministic offline fixture
+and `/tokens` for real provider-reported usage in the current run.
+
 ## Documentation
 
 - [Interactive interface and sessions](docs/interactive-reference.md)
@@ -163,7 +208,7 @@ noah update
 ## Development
 
 ```bash
-uv sync --extra dev
+uv sync --extra dev --extra mcp --extra tracing
 uv run ruff check src tests
 uv run pytest tests
 uv build

{noah_code-0.1.1 → noah_code-0.2.0}/README.md

@@ -28,8 +28,12 @@ and seccomp support. You also need an LLM provider account such as OpenAI, Anthr
 ## Features
 
 - Read files, search with ripgrep, and inspect Git status, diffs, and history.
-- Edit files with anchored replacements, full rewrites, and concurrent-change detection.
-- Run permission-gated shell commands with timeouts and streamed output.
+- Navigate definitions, implementations, references, symbols, hover types, and diagnostics through
+  lazily launched language servers plus an mtime-cached repository map.
+- Edit files with anchored replacements or atomic multi-file patches with exact preimages,
+  rollback, immediate diagnostics, and concurrent-change detection.
+- Run permission-gated shell commands with timeouts and streamed output, or own long-running
+  servers and watchers as bounded background jobs with cursor-based logs.
 - Follow repository instructions from `AGENTS.md`, `CLAUDE.md`, and `.noah-code/instructions.md`.
 - Switch between implementation-focused **build** mode and read-only **plan** mode.
 - Approve actions once or for a session with ordered `allow`, `ask`, and `deny` rules.
@@ -37,7 +41,12 @@ and seccomp support. You also need an LLM provider account such as OpenAI, Anthr
 - Work in an adaptive Atom One Dark cockpit, a classic console, or one-shot non-interactive mode.
 - Type `/` for a live-filtering command and configuration reference; press Enter to send.
 - Follow batched live tool output, then inspect compact execution records with `F2`.
+- Review `/diff` in a keyboard-driven staged/worktree ledger with per-file patches, line deltas,
+  validation state, changed symbols, explicit revert, and checkpoint undo.
 - Resume workspace-scoped sessions with todos and automatic context compaction.
+- Keep full oversized tool results privately while sending the model a focused, reopenable preview.
+- Inspect token, prompt-cache, model-wait, and tool-output usage with `/tokens`; switch live
+  `fast`, `balanced`, and `deep` budgets with `/efficiency`.
 - Switch AI models between turns, with optional cross-repository defaults.
 - Extend workflows with slash commands, opt-in skills, MCP servers, model selection, and tracing.
 
@@ -84,21 +93,55 @@ noah --version
 noah doctor .
 noah config show .
 noah update --check
+noah benchmark .
 ```
 
+Bring your own API key from inside the TUI by entering `/model`: choose the provider, paste the
+key into the masked field, choose the model, then select its reasoning effort. Noah saves the key to the operating system's
+credential store when one is available; otherwise it remains available only to that Noah process.
+API-key values are never written to Noah config, repository, or session files.
+
+Environment variables and the CLI remain available for scripts and headless use:
+
+```bash
+export OPENAI_API_KEY="..."        # or ANTHROPIC_API_KEY / OPENROUTER_API_KEY
+noah providers list
+noah providers add openai --model MODEL_NAME
+noah .
+```
+
+For reasoning models, choose `default`, `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
+Provider and model support varies; `default` omits the parameter. You can set it in the guided
+`/model` flow, switch it live with `/reasoning high`, or launch with:
+
+```bash
+uv run noah --model openai/MODEL --reasoning-effort high .
+```
+
+Custom OpenAI-compatible gateways, vLLM, LM Studio, Ollama, Azure OpenAI, Bedrock, Gemini, Groq,
+Mistral, xAI, DeepSeek, Together AI, and Perplexity are also supported. See the
+[provider configuration guide](docs/configuration.md#bring-your-own-api-provider).
+
 The package also installs `noah-code` and `nc` as equivalent entry points. Because `nc` commonly
-refers to netcat, `noah` or `noah-code` is recommended. Keep provider API keys in the environment
-or trusted NOOA user configuration, never in a repository or Noah Code session metadata.
+refers to netcat, `noah` or `noah-code` is recommended. Keep provider API keys in the OS
+credential store or environment, never in a repository or Noah Code session metadata.
 
-Inside a session, `/model MODEL` switches the active model immediately and remembers it when that
-session is resumed. It does not change other sessions. Use `/model --global MODEL` when the new
-model should also become the default for future sessions in every repository.
+Inside a session, bare `/model` opens guided provider, API-key, model, and reasoning setup. `/model MODEL`
+switches the active model immediately and remembers it when that session is resumed. It does not
+change other sessions. Use `/model --global MODEL` when the new model should also become the
+default for future sessions in every repository.
 
 The TUI keeps the conversation central and adds a session-and-plan rail on terminals at least
 110 columns wide. Tool output streams in a bounded activity panel and compacts after completion,
 keeping long runs responsive without deleting persisted session data. Press `F2` for activity
 details or `F3` for paginated conversation history.
 
+The default `fast` profile uses compact NOOA trajectory rendering, bounded tool results, batched
+repository inspection, cache-friendly turn-boundary context refresh, and lazy MCP connections. A
+configured `lightweight_model` handles coding-session compaction; deterministic titles avoid an
+otherwise unnecessary model request. Run `noah benchmark .` for the deterministic offline fixture
+and `/tokens` for real provider-reported usage in the current run.
+
 ## Documentation
 
 - [Interactive interface and sessions](docs/interactive-reference.md)
@@ -121,7 +164,7 @@ noah update
 ## Development
 
 ```bash
-uv sync --extra dev
+uv sync --extra dev --extra mcp --extra tracing
 uv run ruff check src tests
 uv run pytest tests
 uv build

noah_code-0.2.0/docs/configuration.md

@@ -0,0 +1,279 @@
+# Configuration, permissions, and updates
+
+## Configuration
+
+Configuration is merged in this order, with later layers taking precedence:
+
+1. Built-in defaults.
+2. User config at `~/.config/noah-code/config.toml`.
+3. Project config at `.noah-code/config.toml`.
+4. `NOAH_CODE_*` environment variables.
+5. CLI flags.
+
+### First-run model setup
+
+The first interactive `noah` launch asks for an AI model before starting the agent. Noah Code
+saves that choice as the top-level `model` in `~/.config/noah-code/config.toml`, making it the
+default for every repository. Enter a LiteLLM model name or an alias from the NOOA model registry.
+
+An explicit `noah --model MODEL` on the first launch is saved without prompting. Project config,
+`NOAH_CODE_MODEL`, and later `--model` flags still override the user default according to the
+precedence above. Non-interactive commands such as `noah run`, `doctor`, and `config show` never
+open the onboarding prompt.
+
+Inside an interactive session, switch only the current session or replace the global default:
+
+```text
+/model
+/model openai/MODEL_NAME
+/model --global anthropic/MODEL_NAME
+```
+
+Bare `/model` opens a guided TUI flow: search for a provider, enter its API key in a masked
+field, enter the model ID, and select reasoning effort. Noah attempts to save that key in the operating system credential
+store. If no secure backend is available, the key remains active only in the current Noah process
+and the TUI says so. Keys are never written to Noah configuration or session metadata.
+
+Model switches take effect between turns and are stored in the current session metadata, so a
+resumed session continues with its most recently selected model. A session-only `/model MODEL`
+does not change the user configuration or affect new sessions.
+
+### Bring your own API provider
+
+Enter `/model` for the common provider → API key → model flow. Run `noah providers list` or open
+`/providers` in the TUI for advanced, secret-free setup. Noah supports
+LiteLLM's provider routing and includes guided presets for OpenAI, Anthropic Claude, OpenRouter,
+Google Gemini, Groq, Mistral, xAI, DeepSeek, Together AI, Perplexity, Azure OpenAI, Amazon
+Bedrock, and local Ollama.
+
+For scripting, export credentials before starting Noah and select a provider/model:
+
+```bash
+# OpenAI
+export OPENAI_API_KEY="..."
+noah providers add openai --model MODEL_NAME
+
+# Anthropic Claude
+export ANTHROPIC_API_KEY="..."
+noah providers add anthropic --model MODEL_NAME
+
+# OpenRouter
+export OPENROUTER_API_KEY="..."
+noah providers add openrouter --model PROVIDER/MODEL
+
+# Google Gemini (GOOGLE_API_KEY is also accepted)
+export GEMINI_API_KEY="..."
+noah providers add gemini --model MODEL_NAME
+```
+
+Use `--no-set-default` to print a one-launch command without changing Noah's global default.
+Inside Noah, `/providers use openrouter PROVIDER/MODEL` switches the current session and saves the
+new global default.
+
+For vLLM, LM Studio, a company gateway, or another OpenAI-compatible API, create a secret-free
+NOOA model alias:
+
+```bash
+export COMPANY_LLM_API_KEY="..."
+noah providers add custom \
+  --alias company-llm \
+  --model MODEL_ID \
+  --base-url https://llm.example.com/v1 \
+  --api-key-env COMPANY_LLM_API_KEY
+```
+
+The alias is stored in `~/.config/nooa/llm_config.yaml` with mode `0600`. Only the environment
+variable's name is stored. For an unauthenticated local endpoint, omit `--api-key-env`. You can
+then use the alias anywhere a model is accepted: `noah --model company-llm .` or
+`/model company-llm`.
+
+Example user configuration:
+
+```toml
+model = "gpt-4o-mini"
+reasoning_effort = "default" # default, none, minimal, low, medium, high, or xhigh
+lightweight_model = "gpt-4o-mini"
+mode = "build"
+max_iterations = 40
+cell_timeout = 120
+command_timeout = 60
+max_output_chars = 16000
+
+[efficiency]
+profile = "fast"          # "fast", "balanced", or "deep"
+strategy = "lean"         # "standard" is the comparison fallback
+deterministic_titles = true
+lazy_mcp = true
+max_output_lines = 250
+max_search_results = 100
+max_file_results = 500
+tool_output_retention_hours = 24
+
+[lsp]
+enabled = true
+timeout_seconds = 5
+max_symbols = 300
+# Trusted user config may override a language server command:
+# servers.python = ["basedpyright-langserver", "--stdio"]
+
+[processes]
+max_jobs = 8
+max_runtime_seconds = 3600
+max_buffer_chars = 64000
+stop_grace_seconds = 2
+
+[ui]
+theme = "atom-one-dark"
+frontend = "tui"       # "tui" or "console"
+markdown = true
+stream_shell = true
+show_reasoning = false
+
+[summarization]
+policy = "token_budget" # or "none"
+trigger_ratio = 0.35
+preserve_recent = 6
+target_chars = 2500
+
+[tracing]
+enabled = true
+viewer = true
+# jsonl_dir = "~/.local/share/noah-code/traces"
+
+[updates]
+auto_install = true
+interval_hours = 24
+```
+
+Supported environment overrides include:
+
+- `NOAH_CODE_MODEL`
+- `NOAH_CODE_LIGHTWEIGHT_MODEL`
+- `NOAH_CODE_REASONING_EFFORT`
+- `NOAH_CODE_AUTO`
+- `NOAH_CODE_SESSION_DIR`
+- `NOAH_CODE_MODE`
+- `NOAH_CODE_EFFICIENCY`
+- `NOAH_CODE_UNSAFE_INPROCESS`
+- `NOAH_CODE_AUTO_UPDATE`
+
+Repository-controlled configuration cannot weaken the host trust boundary. Project config is
+ignored for `auto_approve`, `efficiency`, `enabled_skills`, `lsp`, `mcp`, `permission_rules`,
+`processes`, `session_dir`, `tracing`, `updates`, and `unsafe_inprocess_code_execution`. Put those
+settings in trusted user config, the environment, or an explicit CLI flag. Language-server
+overrides are user-only because they launch local executables.
+
+A user-configured `permission_rules` array replaces the default rule array. Copy forward every
+default you still want before adding overrides. Hard secret, destructive-shell, and plan-mode
+gates remain enforced in code.
+
+Inspect the resolved configuration from the CLI or inside an interactive session. `/config`
+lists every nested path, while an optional path scopes the output. Values whose names look like
+credentials are redacted.
+
+```bash
+noah config show .
+```
+
+```text
+/config
+/config summarization
+/config updates.auto_install
+```
+
+Model and provider configuration follows NOOA conventions, including its model registry,
+environment variables, and configuration under `~/.config/nooa/`. Provider strings not shown in
+the guided list still pass through to LiteLLM, so additional supported services can be selected
+with `--model PROVIDER/MODEL`.
+
+Reasoning effort is passed through NOOA to LiteLLM only when it is not `default`. Supported values
+are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`, but each provider/model may support
+only a subset. Change the current session or the cross-repository default with:
+
+```text
+/reasoning
+/reasoning high
+/reasoning --global low
+```
+
+For headless launches use `--reasoning-effort high`, or add
+`--reasoning-effort high` to `noah providers add ...` when saving a global model default.
+
+### Efficiency and model routing
+
+`fast` is the default: at most 12 CodeAct iterations, 16,000 characters and 250 lines per
+model-facing tool result, and lazy MCP attachment. `balanced` raises the live cap to 24 iterations
+and its preview to 24,000 characters/400 lines. `deep` permits the configured `max_iterations` and
+legacy-sized 80,000-character previews. Switch without restarting:
+
+```text
+/efficiency
+/efficiency balanced
+/efficiency deep
+```
+
+Oversized results are not discarded. Noah writes the exact output to a private cache file for the
+configured retention period, returns a bounded head/tail preview, and gives the agent an output ID
+for focused line-range retrieval. A truncated file preview is never returned as an editable Match
+anchor.
+
+Set `lightweight_model` to route compaction to a faster or cheaper model. If it is omitted, that
+route follows live `/model` switches. Compaction starts at 35% of the active main model's context
+window by default, preserves the six newest events, and writes a coding checkpoint covering the
+objective, decisions, files, validation, blockers, and next steps.
+
+## Modes and permissions
+
+| Mode | Behavior |
+|------|----------|
+| `build` | Reads are allowed; edits and shell commands follow permission rules and ask by default |
+| `plan` | Reads are allowed; file edits and mutating shell commands are denied |
+
+Switch modes with `--mode`, `/mode build`, or `/mode plan`. The active mode is stored with the
+session.
+
+Permission rules are evaluated in order, and the last matching rule wins. The default policy:
+
+- Allows ordinary reads.
+- Denies likely secrets, including `.env` variants, private keys, `.git` internals, and session
+  databases. `.env.example` remains readable.
+- Asks before workspace edits and shell commands.
+- Denies `git push`, `git clean`, and `git reset --hard`.
+- Keeps file tools inside the active workspace and asks before skill or MCP access.
+- Denies plan-mode mutations regardless of broader allow rules.
+
+`--auto` changes ask decisions to allow but never overrides an explicit deny. Compound shell
+commands and mutating or unrecognized Git commands cannot be silently auto-approved.
+
+## Installation and updates
+
+The README executes the checked-in bootstrapper directly from GitHub. From a local clone, run the
+same installer with:
+
+```bash
+sh install.sh
+```
+
+Installs created by the one-line command check PyPI at most once every 24 hours and install newer
+Noah Code releases through uv. When an update is installed, Noah exits before starting the task
+so it cannot mix old and new runtime modules. Rerun the command to continue on the new version.
+
+```bash
+# Check without changing the installation
+noah update --check
+
+# Update immediately
+noah update
+```
+
+Disable automatic installation from trusted user configuration or the environment:
+
+```toml
+[updates]
+auto_install = false
+interval_hours = 24
+```
+
+```bash
+export NOAH_CODE_AUTO_UPDATE=0
+```

{noah_code-0.1.1 → noah_code-0.2.0}/docs/development.md

@@ -5,7 +5,7 @@
 Install the development environment and run the local checks:
 
 ```bash
-uv sync --extra dev
+uv sync --extra dev --extra mcp --extra tracing
 uv run ruff check src tests
 uv run pytest tests
 uv build
@@ -13,6 +13,17 @@ uv build
 
 The default test suite is hermetic and does not require network access or provider keys.
 
+Run the deterministic efficiency fixture without making provider calls:
+
+```bash
+uv run noah benchmark .
+uv run noah benchmark . --json
+```
+
+It compares standard and lean NOOA trajectory rendering, then measures the configured managed
+preview against a fixed high-volume tool result. The report uses a transparent four-characters-
+per-token estimate; use `/tokens` during a real session for provider-reported usage.
+
 ## CI
 
 GitHub Actions runs the complete test suite on Python 3.12 and 3.13, plus platform smoke tests on

noah_code-0.2.0/docs/extensions.md

@@ -0,0 +1,94 @@
+# Commands, skills, MCP, and tracing
+
+## Custom slash commands
+
+Add reusable Markdown prompts in either location:
+
+- `~/.config/noah-code/commands/*.md` for user commands.
+- `.noah-code/commands/*.md` for repository commands. Repository commands override user commands
+  with the same name.
+
+For example, `.noah-code/commands/fix.md`:
+
+```markdown
+---
+description: Fix a bug and run focused tests
+mode: build
+---
+Fix $ARGUMENTS. Inspect nearby tests, make the smallest coherent change, and run the focused
+test.
+```
+
+Invoke it as `/fix the parser`. Commands support `$ARGUMENTS` and positional placeholders `$1`
+through `$9`. Front matter may also select a mode or model.
+
+## Skills
+
+Open the dedicated searchable picker with `/skills` or `Ctrl+K`. Selecting a document skill
+inserts `$skill-name ` into the composer so you can add the task directly. Noah reads the standard
+`SKILL.md` directory format used by Codex and Claude, including companion `scripts/`, `references/`,
+and `assets/` folders.
+
+Project skills are discovered before user skills from:
+
+- `.agents/skills/`
+- `.claude/skills/`
+- `.noah-code/skills/`
+- `./skills/`
+- `~/.agents/skills/`
+- `~/.claude/skills/`
+- `~/.codex/skills/`
+- `~/.config/noah-code/skills/`
+
+Add an existing skill folder from the picker or the terminal:
+
+```text
+/skills add ~/path/to/my-skill
+```
+
+Noah validates the `SKILL.md` front matter, copies the whole directory to the shared
+`~/.agents/skills/` root, and will not overwrite an existing skill. Skills that depend on a
+vendor-specific runtime, binary, or remote tool still require that dependency to be installed.
+
+Discovery does not grant access. Activate trusted skills from user configuration with patterns
+such as:
+
+```toml
+enabled_skills = ["cmd.*"]
+```
+
+Explicit `$skill-name TASK` invocation is also gated by the `skill` permission category. Project
+configuration cannot activate skills.
+
+## MCP
+
+MCP support is optional:
+
+```bash
+uv sync --extra mcp
+```
+
+Open `/mcp` to search configured servers, connect one, or add a server through the guided STDIO
+and Streamable HTTP setup. Terminal equivalents are:
+
+```text
+/mcp add stdio filesystem npx -y @modelcontextprotocol/server-filesystem /path
+/mcp add http remote https://example.com/mcp
+/mcp connect filesystem
+```
+
+Noah reads the portable `{"mcpServers": {...}}` structure from `.mcp.json`,
+`.noah-code/mcp.json`, and `~/.config/noah-code/mcp.json`. The guided setup writes to the user
+file with mode `0600`; use environment variables or a manually edited config for secrets and auth
+headers. STDIO, SSE, Streamable HTTP, custom headers, and OAuth fields are passed through to the
+MCP runtime. Under the default `lazy_mcp` setting, servers are cataloged but not connected at
+startup, keeping unused schemas and connection latency out of the session. Select a server in
+`/mcp` or run `/mcp connect NAME` to attach it to the live agent. Attachment is gated by the `mcp`
+permission category and asks by default. Set `efficiency.lazy_mcp = false` in trusted user
+configuration only when eager attachment is desired.
+
+## Tracing
+
+Noah Code integrates with NOOA tracing. When a local viewer is available, spans can be exported
+to it. JSONL export can also be enabled in user configuration. Use `/trace` to inspect the active
+destination.