tunacode-cli 0.2.0__tar.gz → 0.2.1__tar.gz

tunacode_cli-0.2.1/.githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE" ]]; do
+    HOOK_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+    SOURCE="$(readlink "$SOURCE")"
+    [[ "$SOURCE" != /* ]] && SOURCE="$HOOK_DIR/$SOURCE"
+done
+HOOK_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+exec "$HOOK_DIR/../scripts/run-pre-commit-hook.sh" pre-commit "$@"

tunacode_cli-0.2.1/.githooks/pre-push

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE" ]]; do
+    HOOK_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+    SOURCE="$(readlink "$SOURCE")"
+    [[ "$SOURCE" != /* ]] && SOURCE="$HOOK_DIR/$SOURCE"
+done
+HOOK_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+exec "$HOOK_DIR/../scripts/run-pre-commit-hook.sh" pre-push "$@"

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/.github/pull_request_template.md

@@ -33,7 +33,7 @@
 - [ ] All pre-commit hooks pass
 - [ ] Code formatted with `ruff format`
 - [ ] Code passes `ruff check` without warnings
-- [ ] No Python file exceeds **600 lines**
+- [ ] No non-test Python file exceeds **600 lines**
 
 ## Checklist
 - [ ] My code follows the Python coding standards (type hints, f-strings, pathlib, etc.)

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/.github/workflows/lint.yml

@@ -22,6 +22,7 @@ jobs:
         run: |
           uv run unimport --check --gitignore --exclude 'venv/*' --exclude '.venv/*' --exclude '.uv-cache/*' --exclude '.uv_cache/*' src
           uv run vulture --min-confidence 80 scripts/utils/vulture_whitelist.py src
+          uv run python scripts/check_stale_symbol_surfaces.py
       - name: Check for orphan modules
         run: uv run python scripts/check_unused_modules.py
 

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/.gitignore

@@ -60,6 +60,7 @@ REFACTOR*
 todo.md
 
 # Agent workflow temporary files
+.artifacts/
 .current_scratchpad_file
 .current_qa_log_path
 .qa_temp/

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/.pre-commit-config.yaml

@@ -68,6 +68,13 @@ repos:
         files: \.py$
         stages: [pre-commit]
 
+      - id: stale-symbol-surfaces
+        name: Check for stale symbol surfaces
+        entry: uv run python scripts/check_stale_symbol_surfaces.py
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+
       - id: vulture-changed
         name: Check for dead code in changed files
         entry: uv run vulture --min-confidence 80 scripts/utils/vulture_whitelist.py
@@ -104,7 +111,7 @@ repos:
         entry: scripts/check-file-length.sh
         language: script
         files: \.py$
-        exclude: ^tests/benchmarks/bench_discover\.py$
+        exclude: ^tests/|^tests/benchmarks/bench_discover\.py$
         pass_filenames: true
 
       # Check naming conventions
@@ -142,6 +149,15 @@ repos:
         pass_filenames: false
         stages: [pre-push]
 
+      - id: ast-grep-getattr-ratchet
+        name: Run ast-grep getattr ratchet
+        entry: scripts/run_ast_grep_checks.sh
+        language: script
+        files: ^(src/.*\.py|rules/ast-grep/.*|scripts/run_ast_grep_checks\.sh|scripts/validate_ast_grep_rules\.py|scripts/check_ast_grep_baseline\.py)$
+        always_run: true
+        pass_filenames: false
+        stages: [pre-push]
+
       # Check for empty directories or __init__.py-only directories (runs on push)
       - id: empty-dir-check
         name: Check for Empty Directories
@@ -150,6 +166,15 @@ repos:
         pass_filenames: false
         stages: [pre-push]
 
+      - id: markdown-frontmatter
+        name: Require markdown frontmatter in root/docs
+        entry: uv run python scripts/check_markdown_frontmatter.py
+        language: system
+        files: ^docs/.*\.md$|^[^/]+\.md$
+        exclude: ^(AGENTS|README)\.md$
+        pass_filenames: false
+        stages: [pre-push]
+
       # Dependency layer check (runs on commit - architectural check)
       # Note: Map visualization generated by GitHub Action on master pushes
       - id: dependency-layers

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/AGENTS.md

@@ -1,5 +1,5 @@
 # AGENTS.md
-Last Updated: 2026-04-02
+Last Updated: 2026-04-27
 
 ## Repository Orientation
 - This is `tunacode-cli`, a terminal AI coding agent with a Textual UI and tiny-agent tool loop.
@@ -9,11 +9,11 @@ Last Updated: 2026-04-02
 
 
 ## Start Here
-- `README.md` — user-facing setup, supported features, and command usage.
 - `docs/modules/index.md` — module layer map and reading order.
 - `docs/architecture/dependencies/DEPENDENCY_LAYERS.md` — generated dependency summary.
 - `docs/skills/audit-harness/SKILL.md` — strict harness-audit procedure; treat any mismatch or failed gate as critical and run checks manually one by one.
 - `docs/modules/ui/commands.md` — command model and command registration notes.
+- `docs/workflows/README.md` — accepted development workflows and execution guidance.
 - `scripts/check_agents_freshness.py` — validates this file is current.
 
 ## Harness Documentation Purpose
@@ -24,6 +24,7 @@ Last Updated: 2026-04-02
 
 ## Git Safety and Non-Destructive Defaults
 - Follow `docs/git/practices.md` for local Git workflow and safety rules.
+- Use `docs/git/changelog-update.md` when the task is to refresh `CHANGELOG.md` from recently merged PRs.
 - Before performing any Git operation (`git status`, `git add`, `git commit`, etc.), read `docs/git/practices.md` in that session.
 - Default behavior is non-destructive: never delete or clean untracked files/directories unless explicitly requested by the user.
 - If unknown files appear during checks, pause and ask before cleanup.
@@ -44,7 +45,7 @@ Last Updated: 2026-04-02
 - Developer entry: `Makefile` target `make run` -> `uv run tunacode`.
 
 ## Source Structure (high-level)
-- `src/tunacode/ui/` — terminal UI, widgets, screens, CSS, command shell.
+- `src/tunacode/ui/` — terminal UI, widgets, screens, CSS, command shell, and render-safety helpers for Rich/Textual theme stability.
 - `src/tunacode/core/` — agents, compaction, session, prompting, logging.
 - `src/tunacode/tools/` — native tinyagent tool implementations (`bash`, `discover`, `read_file`, `hashline_edit`, `web_fetch`, `write_file`) plus supporting helpers.
 - `src/tunacode/configuration/` — settings, model registry, API paths, limits, pricing, and ignore patterns.
@@ -52,7 +53,7 @@ Last Updated: 2026-04-02
 - `src/tunacode/utils/` — adapters, messaging helpers, token counting, gitignore, system utilities.
 - `src/tunacode/types/` — canonical data models, callbacks, protocol types.
 - Shared packages: `src/tunacode/constants.py`, `src/tunacode/exceptions.py`, `src/tunacode/skills/`, `src/tunacode/prompts/`.
-- Notable sub-packages: `src/tunacode/core/ui_api/` (core→UI bridge), `src/tunacode/tools/lsp/` (LSP client integration).
+- Notable sub-packages: `src/tunacode/core/ui_api/` (core→UI bridge).
 
 ## Architecture Boundaries
 - Documented conceptual stack (bottom-up): `types -> utils -> infrastructure -> configuration -> tools -> core -> ui`.
@@ -69,6 +70,9 @@ Last Updated: 2026-04-02
 - Review notes for active PR triage: `docs/reviews/`.
 - Debugging and investigation artifacts: `docs/reviews/*-artifact.md`.
 - Git workflow and safety practices: `docs/git/practices.md`.
+- Changelog refresh procedure for merged PR summaries: `docs/git/changelog-update.md`.
+- Workflow guidance: `docs/workflows/README.md` and workflow-specific files such
+  as `docs/workflows/REFACTOR.md`.
 - Module-specific docs:
   - `docs/modules/core/core.md`
   - `docs/modules/ui/ui.md`
@@ -83,8 +87,9 @@ Last Updated: 2026-04-02
 - UI design reference: `docs/ui/css-architecture.md` and generated map at `docs/codebase-map/structure/tree-structure.txt`.
 
 ## Routine Commands
-- Setup: `make dev-setup`.
-- Install/update dependencies: `make install`.
+- Setup: `make install` (canonical full dev environment bootstrap).
+  - Installs repo-managed `pre-commit` and `pre-push` git hooks from `.githooks/`.
+- Compatibility alias: `make dev-setup`.
 - Run app: `make run`.
 - Full tests: `make test`.
 - Linters + hooks: `make lint`.
@@ -110,6 +115,7 @@ Last Updated: 2026-04-02
 ## Quality Constraints (Do not break)
 - `README.md` and docs should stay consistent with implementation.
 - Keep `AGENTS.md` updated with `Last Updated: YYYY-MM-DD` whenever `src/` or `docs/` changes.
+- The 2026-04-13 getattr baseline follow-up reduced the scoped UI/runtime and owned-exception `getattr(...)` usage; the committed ast-grep baseline should stay aligned with those removals.
 - Do not add TunaCode-owned message-contract wrappers around tinyagent message types; use tinyagent models directly in memory and keep dict payloads at real boundaries.
 - Preserve existing architecture order rules; do not add new imports across forbidden layers.
 - Treat current file-length allowlist entries as temporary debt only. Do not add any new file-specific exemptions to the `>600` line rule; fix the enforcement path or split the code instead.
@@ -121,4 +127,5 @@ Last Updated: 2026-04-02
 - Prefer small, scoped changes.
 - Keep edits minimal and targeted.
 - Prefer existing patterns; mirror command/test naming used in nearby code.
+- Treat `src/tunacode/ui/render_safety.py` plus built-in theme wrapping in `src/tunacode/constants.py` as part of the startup/theme stability path; keep Rich default/ANSI color handling local to TunaCode rather than patching Textual.
 - Run validation commands before handoff when touching architecture, dependencies, or shared packages.

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/CHANGELOG.md

@@ -1,3 +1,12 @@
+---
+title: Changelog
+summary: Release history for TunaCode versions and notable changes.
+when_to_read:
+  - When preparing a release note
+  - When reviewing past changes or version history
+last_updated: "2026-04-27"
+---
+
 # Changelog
 
 All notable changes to this project will be documented in this file.
@@ -7,6 +16,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-04-27
+
+### Added
+- Added a stale-symbol surface checker, related unit coverage, and lint/pre-push enforcement to catch dead re-export and annotation-only APIs.
+
+### Changed
+- Simplified stream orchestration and interrupted-stream cleanup by moving the stream loop into a dedicated module, tracking per-stream baselines, and tightening callback typing.
+- Removed dead agent component helpers and legacy dangling-tool-call patching paths from the runtime cleanup flow.
+- Documented explicit `bug:`/`refactor:` style labels for issues and PRs and clarified that the repository root `README.md` is exempt from markdown frontmatter requirements.
+- Updated release-gate enums to `StrEnum` and restored tmux marker selection for the release E2E test.
+
+### Fixed
+- Fixed abort-time tool reconciliation so completed tool results are preserved and interrupted tool calls are patched with explicit error results instead of rolling history back.
+- Fixed Textual startup and theme-switch rendering crashes by hardening built-in theme colors and normalizing Rich dim/default styles before Textual filtering.
+
 ## [0.2.0] - 2026-04-02
 
 ### Changed

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/HARNESS.md

@@ -1,9 +1,20 @@
+---
+title: Harness
+summary: Repository code-quality harness for hooks, CI checks, and local enforcement.
+when_to_read:
+  - When auditing pre-commit or pre-push hooks
+  - When checking local and CI enforcement behavior
+last_updated: "2026-04-13"
+---
+
 # HARNESS.md
 
 ## Pre-commits
 
 Source of truth: `.pre-commit-config.yaml`
 
+Git hook entrypoints are repo-managed wrappers in `.githooks/`, installed into `.git/hooks/` as relative symlinks by `scripts/install-git-hooks.sh`. This keeps hook execution tied to the checkout's local `.venv` after the repository directory moves.
+
 ### Global pre-commit settings
 - Python runtime: `python3`
 - Global exclude regex:
@@ -35,10 +46,13 @@ Source of truth: `.pre-commit-config.yaml`
 - `ruff` (repo: `astral-sh/ruff-pre-commit`, args: `--fix --show-fixes`)
 - `ruff-format` (repo: `astral-sh/ruff-pre-commit`, excludes `models_registry.json`)
 - `dead-imports` (repo: `local`, entry: `scripts/run-dead-imports.sh`, files: `\.py$`)
+- `stale-symbol-surfaces` (repo: `local`, entry: `uv run python scripts/check_stale_symbol_surfaces.py`, stage: `pre-push`)
+  - Detects public symbols that survive only via package `__init__` re-exports or same-module annotation scaffolding.
 - `vulture-changed` (repo: `local`, entry: `uv run vulture --min-confidence 80 scripts/utils/vulture_whitelist.py`, files: `^src/.*\.py$`, exclude: `tests/|test_`)
 - `naming-conventions` (repo: `local`, entry: `uv run python scripts/check-naming-conventions.py`, files: `^src/.*\.py$`, exclude: `tests/|scripts/`)
 - `defensive-slop` (repo: `local`, entry: `uv run python scripts/check-defensive-slop.py`, files: `^src/.*\.py$`, stages: `pre-commit`, `pre-push`)
-- `check-file-length` (repo: `local`, entry: `scripts/check-file-length.sh`, files: `\.py$`, exclude: `tests/benchmarks/bench_discover.py`)
+- `check-file-length` (repo: `local`, entry: `scripts/check-file-length.sh`, files: `\.py$`, exclude: `tests/`)
+  - Current behavior: enforces the `>600` line rule for non-test Python files only. All files under `tests/` are intentionally excluded from this gate.
 
 #### Security and safeguards
 - `bandit` (repo: `PyCQA/bandit`, args: `-c pyproject.toml`, dep: `bandit[toml]`)
@@ -55,6 +69,7 @@ Source of truth: `.pre-commit-config.yaml`
 - `tests/architecture/test_init_bloat.py` enforces thin `__init__.py` modules.
 - `scripts/check_agents_freshness.py` validates `AGENTS.md` freshness against recent `src/` and `docs/` changes.
 - `doc8` (repo: `pycqa/doc8`, args: `--max-line-length=120`)
+  - Current behavior: the hook is configured, but `pre-commit run doc8 --all-files` skips in this repository because no matching doc8-supported files are selected.
 
 ### Currently disabled in config
 - `isort` (commented out; replaced by Ruff import sorting)
@@ -66,10 +81,14 @@ Pre-push hooks run from `.pre-commit-config.yaml` with stage `pre-push`.
 
 ### Active pre-push hooks
 - `mypy` (local, `uv run mypy --ignore-missing-imports --no-strict-optional`, scoped to `src/**/*.py`)
+- `stale-symbol-surfaces` (local, `uv run python scripts/check_stale_symbol_surfaces.py`)
 - `defensive-slop` (local, `uv run python scripts/check-defensive-slop.py`, scoped to `src/**/*.py`)
 - `pylint-duplicates` (local, duplicate-code check)
 - `pytest` (local, `uv run pytest -x -q`)
+- `ast-grep-getattr-ratchet` (local, `scripts/run_ast_grep_checks.sh`, scoped to `src/**/*.py`, `rules/ast-grep/**`, and ast-grep helper scripts)
+  - Validates the ast-grep rule file, runs the rule test, then scans all of `src/` for `getattr(...)` and fails only on findings not present in the committed baseline.
 - `empty-dir-check` (local, `uv run python scripts/utils/check_empty_dirs.py`)
+- `markdown-frontmatter` (local, `uv run python scripts/check_markdown_frontmatter.py`, scoped to repo-root/docs markdown except `AGENTS.md` and root `README.md`)
 
 ### Run hooks manually
 - Canonical local harness entrypoint: `make check`
@@ -89,7 +108,7 @@ Pre-push hooks run from `.pre-commit-config.yaml` with stage `pre-push`.
 - Local source of truth: `make check` runs the full pre-commit and pre-push hook stages across all files, plus the CI enforcement checks for full dead-code scan, orphan-module detection, and `deptry`.
 - Local supplemental check: `uv run python scripts/run_gates.py` is a subset spot-check and does not mirror the full local or CI harness.
 - CI enforcement: pre-commit and pre-push remain the first enforcement line before CI.
-- CI enforcement: `.github/workflows/lint.yml` runs `pre-commit`, full dead-code checks, orphan-module detection, and a separate `deptry` job.
+- CI enforcement: `.github/workflows/lint.yml` runs `pre-commit`, full dead-code checks, stale symbol surface detection, orphan-module detection, and a separate `deptry` job.
 - CI enforcement: `.github/workflows/empty-dir-check.yml` enforces the empty-directory / `__init__.py`-only directory rule in CI.
 - CI artifact generation: `.github/workflows/dependency-map.yml` runs on pushes to `main`/`master`, regenerates `docs/architecture/dependencies/DEPENDENCY_LAYERS.*`, and pushes changes to `automation/dependency-map` for PR review.
 - CI report / issue automation: `.github/workflows/tech-debt.yml` scans TODO/FIXME-style debt and the scheduled report job can open or update a GitHub issue.

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/Makefile

@@ -7,8 +7,8 @@
 help:
 	@echo "Tunacode Development Commands:"
 	@echo ""
-	@echo "  make dev-setup  - Full setup for fresh clone (installs deps, hooks)"
-	@echo "  make install    - Install/update dependencies"
+	@echo "  make install    - Cleanly bootstrap the verified dev environment"
+	@echo "  make dev-setup  - Alias for make install"
 	@echo "  make run        - Run the development server"
 	@echo "  make test       - Run test suite"
 	@echo "  make test-tmux  - Run the tmux system test suite"
@@ -17,13 +17,12 @@ help:
 	@echo "  make clean      - Clean build artifacts"
 	@echo ""
 
-# Full setup for fresh clone
-dev-setup:
+# Cleanly bootstrap the full development environment
+install:
 	@bash scripts/dev-setup.sh
 
-# Install/update dependencies
-install:
-	uv sync --extra dev
+# Backwards-compatible alias for the canonical install target
+dev-setup: install
 
 # Run the development server
 run:

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tunacode-cli
-Version: 0.2.0
+Version: 0.2.1
 Summary: Your agentic CLI developer.
 Project-URL: Homepage, https://tunacode.xyz/
 Project-URL: Repository, https://github.com/alchemiststudiosDOTai/tunacode
@@ -74,13 +74,11 @@ A terminal-based AI coding agent with a NeXTSTEP-inspired interface.
 
 ## Features
 
-- **Any model** - Works with any OpenAI-compatible API (Anthropic, OpenAI, Google, Ollama, vLLM, etc.)
-- **Native tinyagent tools** - Direct tinyagent tool contracts with no legacy wrapper compatibility layer
+- **Any model** - Works with any OpenAI-compatible API
 - **File operations** - Read files with hash-tagged lines, create files, and edit existing files with hash-validated references
 - **Shell access** - Run bash commands with output capture
 - **Repository discovery** - Use `discover` for natural-language code search and repository exploration
 - **Session persistence** - Resume previous conversations with `/resume`
-- **LSP diagnostics** - Real-time code errors after file writes (Python, TypeScript, Go, Rust)
 - **Themeable UI** - CSS-based theming with NeXTSTEP-inspired design
 - **Text selection + clipboard copy** - Mouse selection works across Rich-rendered chat content; copy with `ctrl+y` or `ctrl+shift+c`
 - **Agent loop** - Powered by [tinyAgent](https://github.com/alchemiststudiosDOTai/tinyAgent)
@@ -112,7 +110,7 @@ pip install tunacode-cli
 ```bash
 git clone https://github.com/alchemiststudiosDOTai/tunacode.git
 cd tunacode
-make dev-setup
+make install
 ```
 
 Or without make:
@@ -127,14 +125,16 @@ cd tunacode
 Common development tasks:
 
 ```bash
-make dev-setup  # Full setup for fresh clone
-make install    # Install/update dependencies
+make install    # Cleanly bootstrap the verified dev environment
+make dev-setup  # Alias for make install
 make run        # Run the development server
 make test       # Run test suite
 make lint       # Run linters
 make clean      # Clean build artifacts
 ```
 
+`make install` also installs repo-managed `pre-commit` and `pre-push` hooks from `.githooks/` using relative symlinks, so moving the checkout does not strand the hooks on an old absolute virtualenv path.
+
 View technical debt:
 
 ```bash
@@ -188,16 +188,6 @@ Slash commands are command objects in `tunacode.ui.commands`; each one is a `Com
 | `/exit` | Exit TunaCode |
 | `exit` | Legacy alias for exit |
 
-### Confirm Parallel Tool Calls
-
-Run `/debug` to enable lifecycle logs. During agent execution, parallel batches are reported with lines prefixed by:
-
-- `[LIFECYCLE] Parallel tool calls active: ...`
-- `[LIFECYCLE] Parallel tool calls update: ...`
-- `[LIFECYCLE] Parallel tool calls complete`
-
-If no `Parallel tool calls` lifecycle lines appear, that request did not execute a parallel tool batch.
-## Tools
 
 The agent has access to:
 
@@ -210,7 +200,6 @@ The agent has access to:
 | `web_fetch` | Fetch web page content |
 | `write_file` | Create new files |
 
-TunaCode now uses the native tinyagent tool surface directly. Legacy wrapper-based tools such as `update_file`, `glob`, `grep`, and `list_dir` are removed rather than translated through a compatibility layer.
 
 Important tool rules:
 
@@ -223,17 +212,6 @@ Important tool rules:
 
 <img src="assets/hashline-edit.png" alt="hashline-edit tool in tunacode" width="600"/>
 
-## LSP Integration
-
-Automatic code diagnostics when LSP servers are in PATH:
-
-| Language | Server |
-|----------|--------|
-| Python | `ruff server` |
-| TypeScript/JS | `typescript-language-server` |
-| Go | `gopls` |
-| Rust | `rust-analyzer` |
-
 ## Security
 
 TunaCode has **full shell access** with no permission prompts. If you're concerned:

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/README.md

@@ -14,13 +14,11 @@ A terminal-based AI coding agent with a NeXTSTEP-inspired interface.
 
 ## Features
 
-- **Any model** - Works with any OpenAI-compatible API (Anthropic, OpenAI, Google, Ollama, vLLM, etc.)
-- **Native tinyagent tools** - Direct tinyagent tool contracts with no legacy wrapper compatibility layer
+- **Any model** - Works with any OpenAI-compatible API
 - **File operations** - Read files with hash-tagged lines, create files, and edit existing files with hash-validated references
 - **Shell access** - Run bash commands with output capture
 - **Repository discovery** - Use `discover` for natural-language code search and repository exploration
 - **Session persistence** - Resume previous conversations with `/resume`
-- **LSP diagnostics** - Real-time code errors after file writes (Python, TypeScript, Go, Rust)
 - **Themeable UI** - CSS-based theming with NeXTSTEP-inspired design
 - **Text selection + clipboard copy** - Mouse selection works across Rich-rendered chat content; copy with `ctrl+y` or `ctrl+shift+c`
 - **Agent loop** - Powered by [tinyAgent](https://github.com/alchemiststudiosDOTai/tinyAgent)
@@ -52,7 +50,7 @@ pip install tunacode-cli
 ```bash
 git clone https://github.com/alchemiststudiosDOTai/tunacode.git
 cd tunacode
-make dev-setup
+make install
 ```
 
 Or without make:
@@ -67,14 +65,16 @@ cd tunacode
 Common development tasks:
 
 ```bash
-make dev-setup  # Full setup for fresh clone
-make install    # Install/update dependencies
+make install    # Cleanly bootstrap the verified dev environment
+make dev-setup  # Alias for make install
 make run        # Run the development server
 make test       # Run test suite
 make lint       # Run linters
 make clean      # Clean build artifacts
 ```
 
+`make install` also installs repo-managed `pre-commit` and `pre-push` hooks from `.githooks/` using relative symlinks, so moving the checkout does not strand the hooks on an old absolute virtualenv path.
+
 View technical debt:
 
 ```bash
@@ -128,16 +128,6 @@ Slash commands are command objects in `tunacode.ui.commands`; each one is a `Com
 | `/exit` | Exit TunaCode |
 | `exit` | Legacy alias for exit |
 
-### Confirm Parallel Tool Calls
-
-Run `/debug` to enable lifecycle logs. During agent execution, parallel batches are reported with lines prefixed by:
-
-- `[LIFECYCLE] Parallel tool calls active: ...`
-- `[LIFECYCLE] Parallel tool calls update: ...`
-- `[LIFECYCLE] Parallel tool calls complete`
-
-If no `Parallel tool calls` lifecycle lines appear, that request did not execute a parallel tool batch.
-## Tools
 
 The agent has access to:
 
@@ -150,7 +140,6 @@ The agent has access to:
 | `web_fetch` | Fetch web page content |
 | `write_file` | Create new files |
 
-TunaCode now uses the native tinyagent tool surface directly. Legacy wrapper-based tools such as `update_file`, `glob`, `grep`, and `list_dir` are removed rather than translated through a compatibility layer.
 
 Important tool rules:
 
@@ -163,17 +152,6 @@ Important tool rules:
 
 <img src="assets/hashline-edit.png" alt="hashline-edit tool in tunacode" width="600"/>
 
-## LSP Integration
-
-Automatic code diagnostics when LSP servers are in PATH:
-
-| Language | Server |
-|----------|--------|
-| Python | `ruff server` |
-| TypeScript/JS | `typescript-language-server` |
-| Go | `gopls` |
-| Rust | `rust-analyzer` |
-
 ## Security
 
 TunaCode has **full shell access** with no permission prompts. If you're concerned:

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/docs/CODE-STANDARDS.md

@@ -1,3 +1,12 @@
+---
+title: Code Standards
+summary: Repository coding standards and guardrails for keeping changes simple and scoped.
+when_to_read:
+  - When editing source code
+  - When reviewing local style and complexity rules
+last_updated: "2026-04-04"
+---
+
 # CODE-STANDARDS.md
 
 ## Purpose

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/docs/README.md

@@ -1,3 +1,12 @@
+---
+title: Documentation Index
+summary: Overview of the repository documentation tree and where to find each doc family.
+when_to_read:
+  - When locating documentation
+  - When navigating docs by topic
+last_updated: "2026-04-04"
+---
+
 # Docs
 
 This directory contains project documentation, architecture artifacts, and reference materials for TunaCode.
@@ -21,6 +30,11 @@ This directory contains project documentation, architecture artifacts, and refer
 | `ui/css-architecture.md` | CSS theming and NeXTSTEP-inspired design system |
 | `codebase-map/structure/tree-structure.txt` | Auto-generated source tree structure |
 
+## Markdown Metadata Note
+
+- `README.md` is exempt from any Markdown frontmatter requirement.
+- If a frontmatter rule is applied to docs pages in the future, do not require YAML frontmatter in the repository root `README.md`.
+
 ## Generated Artifacts
 
 - `docs_audit.html` — documentation consistency audit report (review before cleanup)

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/docs/architecture/dependencies/DEPENDENCY_LAYERS.md

@@ -1,3 +1,12 @@
+---
+title: Dependency Layers
+summary: Generated layer dependency summary for the current TunaCode codebase.
+when_to_read:
+  - When auditing layer imports or dependency direction.
+  - When regenerating the dependency map artifact.
+last_updated: "2026-04-04"
+---
+
 # Dependency Layers
 
 Generated: 2026-02-15

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/docs/architecture/patterns/agent-message-serialization.md

@@ -13,6 +13,12 @@ depends_on:
   - src/tunacode/types/canonical.py
 feeds_into:
   - docs/modules/core/core.md
+when_to_read:
+  - Modifying agent message handling
+  - Working on abort/resume logic
+  - Reviewing type boundary violations
+  - Understanding message type ownership
+last_updated: "2026-04-04"
 ---
 
 ## The Problem: Three Type Systems for One Concept

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/docs/codebase-map/structure/tree-structure.txt

@@ -53,8 +53,7 @@ src/tunacode/
 │   │   ├── __init__.py
 │   │   ├── agent_state.py
 │   │   ├── state.py
-│   │   ├── state_structures.py
-│   │   └── tool_registry.py
+│   │   └── state_structures.py
 │   ├── ui_api/
 │   │   ├── __init__.py
 │   │   ├── configuration.py

{tunacode_cli-0.2.0 → tunacode_cli-0.2.1}/docs/deployment.md

@@ -1,3 +1,12 @@
+---
+title: Deployment
+summary: Runbook for publishing tunacode-cli to PyPI and handling the release flow.
+when_to_read:
+  - When preparing a PyPI release
+  - When reviewing the deployment runbook
+last_updated: "2026-04-04"
+---
+
 # Deployment
 
 This document is the repository runbook for publishing `tunacode-cli` to PyPI.

tunacode_cli-0.2.1/docs/git/changelog-update.md

@@ -0,0 +1,73 @@
+---
+title: Changelog Update Procedure
+summary: Manual policy and workflow for refreshing CHANGELOG.md from merged pull requests.
+when_to_read:
+  - When asked to update CHANGELOG.md from recent PRs
+  - When deciding whether a merged PR needs a changelog edit
+last_updated: "2026-04-11"
+---
+
+# Changelog Updates
+
+## Policy
+
+- Updating `CHANGELOG.md` from merged PRs is a manual maintenance task.
+- A PR merging to `master` does **not** automatically require its own changelog edit before merge.
+- Do **not** treat changelog updates as a default merge blocker for normal PR flow.
+- Refresh the `## [Unreleased]` section only when the user explicitly asks for it or when changelog coverage is explicitly part of the task being reviewed.
+
+## Scope
+
+Use this workflow when the goal is to summarize recently merged pull requests into `CHANGELOG.md`.
+
+Do not use it to:
+- add entries for open or unmerged PRs
+- invent release notes without checking the merged PR content
+- force every feature or fix PR to include a changelog change in the same branch
+
+## Workflow
+
+1. Identify the recent merged PRs on `master`.
+
+   Example:
+
+   ```bash
+   gh pr list --state merged --base master --limit 5 \
+     --json number,title,mergedAt,author,url
+   ```
+
+2. Inspect each relevant PR before summarizing it.
+
+   Example:
+
+   ```bash
+   gh pr view 460 --json title,body,files,commits,url
+   ```
+
+3. Update `CHANGELOG.md` under `## [Unreleased]` using the existing Keep a Changelog headings already present in the file.
+
+   Preferred headings:
+   - `### Added`
+   - `### Changed`
+   - `### Fixed`
+   - `### Removed` when needed
+
+4. Write concise user-facing summaries.
+
+   Rules:
+   - summarize the merged outcome, not the implementation play-by-play
+   - group related PRs into a small number of bullets when they land on the same theme
+   - prefer behavior and operator impact over internal refactor detail
+   - avoid duplicating every commit message verbatim
+
+5. Update the document metadata in `CHANGELOG.md` when you edit it.
+
+6. If the user asked for a commit, commit only the changelog/documentation files that are part of the requested update.
+
+## Notes
+
+- This workflow is intentionally not automated.
+- The source of truth is the merged PR set plus the actual PR content, not branch names alone.
+- If the task is ambiguous, clarify whether the user wants:
+  - the last N merged PRs summarized into `Unreleased`, or
+  - a release-specific changelog entry for a versioned cut