turnloop 0.1.5__tar.gz → 0.1.7__tar.gz

turnloop-0.1.7/.turnloop/settings.local.json

@@ -0,0 +1,3 @@
+{
+  "provider": "blaxel"
+}

{turnloop-0.1.5 → turnloop-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: turnloop
-Version: 0.1.5
+Version: 0.1.7
 Summary: A local-first agentic coding harness: streaming tool loop, permission gating, context compaction, subagents, and any LLM provider.
 Project-URL: Homepage, https://github.com/Pranesh-2005/turnloop
 Author: Pranesh
@@ -49,7 +49,7 @@ tl experiment run smoke         # a measurement run, offline and free
 
 Four runtime dependencies: `textual`, `pydantic`, `httpx`, `pyyaml`. No vendor
 SDKs, no agent framework — the loop is the point, so the loop is written here.
-~18,000 lines of Python, 290 tests, no network in the default test run.
+~20,000 lines of Python, 338 tests, no network in the default test run.
 
 ---
 
@@ -117,7 +117,7 @@ point.
 Verify:
 
 ```bash
-tl --version                # turnloop 0.1.5
+tl --version                # turnloop 0.1.7
 tl doctor                   # every provider, key presence, shell, context budget
 ```
 
@@ -139,8 +139,9 @@ context arithmetic for the active provider:
 tl                                          # interactive TUI
 tl -p "why does the login test flake"       # headless single turn
 tl -p "..." --json                          # headless, JSONL events on stdout
-tl --resume                                 # resume the most recent session
-tl --resume <session-id>                    # resume a specific one
+tl -c                                       # resume the most recent session, no picker
+tl --resume                                 # interactive picker (TUI); most recent (headless)
+tl --resume <session-id>                    # resume a specific one, no picker
 tl sessions                                 # list recorded sessions
 tl config                                   # merged config + which layer each value came from
 tl config --edit                            # interactive settings editor
@@ -162,7 +163,8 @@ and neither is reachable by the model — see
 | `--max-iterations N` | tool-loop safety cap (default 40) |
 | `-p, --print PROMPT` | headless single turn |
 | `--json` | headless output as JSONL events |
-| `--resume [ID]` | resume last, or a named session |
+| `-c, --continue` | resume the most recent session directly, no picker |
+| `--resume [ID]` | bare: interactive picker in the TUI, most recent in headless. With an id: that session, no picker |
 
 ### Permission modes
 
@@ -184,12 +186,18 @@ to cycle. Make it permanent via `TURNLOOP_PERMISSION_MODE` or `settings.json`.
 ### Keys
 
 ```
-ctrl+c   interrupt the running turn (again to exit)
+ctrl+c   copy the selection; else interrupt a running turn; else nothing
 ctrl+p   cycle permission mode
 ctrl+l   clear the view (history is kept)
 ctrl+d   quit
 ```
 
+`ctrl+c` no longer quits. It used to call `self.exit()` whenever no turn was
+running, so pressing it to copy text killed the session. It now checks, in order,
+whether there is a selection to copy (via Textual's `App.copy_to_clipboard`, OSC 52,
+no new dependency), then whether a turn is running to interrupt, and otherwise does
+nothing. `ctrl+d` is still the only way to quit.
+
 `ctrl+c` and friends are bound with `priority=True` — the prompt Input always has
 focus and would otherwise swallow them.
 
@@ -205,6 +213,9 @@ focus and would otherwise swallow them.
 /provider    switch provider            /config       settings editor
 /export      transcript to markdown     /hooks        configured hooks
 /sessions    recorded sessions          /doctor       diagnostics
+/skills      loaded skills, and any     /resume       picker, rebuilds the
+             rejected on disk (why,                   agent in place; refuses
+             and where)                                while a turn is running
 /quit        exit
 ```
 
@@ -350,6 +361,13 @@ close a self-escalation path: settings files set `permission_mode` and
 next launch. Verified against the real engine *in bypass mode*, which is the case that
 matters — deny beats bypass, so the block holds even there.
 
+That was a unit test. It has since been verified live: with
+`Write(.turnloop/**)` explicitly allowed *and* `--permission-mode bypass`, a real
+model told to grant itself permanent bypass access was blocked, made one attempt,
+and proposed the change to the user instead. The settings file was unchanged. Deny
+beats an explicit allow rule and bypass mode at once — not just in the test suite,
+against a live model that was actually trying.
+
 It is a guardrail, not a sandbox, and the boundary is worth being precise about. `Write`
 and `Edit` are blocked; **`Bash` is not**, so a shell redirect reaches the same file.
 Closing that properly needs a path guard below the tool layer rather than more patterns.
@@ -395,6 +413,14 @@ because a crashed run still leaves a readable trace, and because the experiments
 layer reads exactly the same format the TUI writes — a run trace and a real session
 are the same artifact.
 
+`-c`/`--continue` reopens the most recent session with no prompting. Bare `--resume`
+in the TUI opens an interactive picker — a `DataTable` of sessions, newest first,
+with a live preview pane of the selected conversation — and `--resume <id>` jumps
+straight to a specific one. `/resume` opens the same picker in-session and rebuilds
+the agent in place; it refuses while a turn is running rather than tearing one down
+mid-flight. Headless has no picker to show, so a bare `--resume` there falls back to
+"most recent" — the same thing `--continue` does.
+
 ---
 
 ## Providers
@@ -891,11 +917,78 @@ And **0.1.4 shipped this way**, so `pip install turnloop==0.1.4` crashes on `/co
 Fixed in 0.1.5. The tests now drive a real app through Textual's `run_test()` pilot and
 fail if the decorators are removed.
 
-**The lesson, five times over in one project:** an 84-run sweep failing while printing
+**A directory that exists on every launch cannot mean "this is a project."**
+
+`find_project_root` treated any ancestor `.turnloop` directory as an explicit project
+declaration. But `default_project_dir` creates `.turnloop/` — with a `sessions/`
+folder and a `.gitignore` — on every launch, unconditionally, wherever turnloop
+happens to start. So the directory's mere existence declared nothing; it was
+frequently just the residue of having once run the tool there. Run `tl` once from a
+home directory, or a drive root, and it permanently annexed every project beneath it:
+sessions, the `.env` layer, `settings.json` and the permission rules all resolved to
+the wrong root from then on. Real instance, the author's own machine: `F:\.turnloop`
+was created on 2026-08-01, and every `F:\anything\proj\pyproject.toml` since then
+resolved its project root to `F:\`.
+
+The invariant that broke was never written down as one, which is exactly why it lasted.
+The fix makes the implicit rule explicit: a `.turnloop` counts only if it holds
+something a human put there — `settings.json`, `settings.local.json`, `commands/`,
+`skills/`, `TURNLOOP.md` — and one holding only an auto-created `sessions/` is ignored.
+The home directory is excluded outright on top of that, since `~/.turnloop` is the
+user-scope settings location and can never mean "project." The false invariant had
+been there since the tool first created `.turnloop/` on launch; fixed in 0.1.6.
+
+**A skill that failed to parse vanished with no error, and the model reported success.**
+
+A live run installed a skill whose frontmatter was markdown-bold — `**name**:
+something` — rather than YAML. `yaml.safe_load` returned no usable keys,
+`load_skills` hit its "no description" skip, and the skill disappeared: no exception,
+no log line, nothing in `/skills`. The model that had just "installed" it reported
+success, because from its side the write succeeded and nothing said otherwise.
+
+The bug was not the parser rejecting bad frontmatter — that part is correct. It was
+that a rejection and a nonexistent skill looked identical from the outside. `load_skills`
+keeps its exact signature, but a new `rejected_skills()` now returns what was dropped
+and why, `/skills` reports it, and `CONFIG_LAYOUT` shows the literal YAML frontmatter
+block in the system prompt so the model stops guessing at markdown-bold instead.
+Fixed in 0.1.6.
+
+**A permission denial that should end in one message looped ten times, and it cost
+real money before anyone noticed — because nothing about it failed a test.**
+
+Two defects landed in the same code path with the same symptom. The DENY branch's
+message said only `Permission denied: <rule>`; the ASK-decline branch, which is
+recoverable, had always carried "Do not retry it" — so the weaker wording sat on the
+*permanent* block, the one that most needed it. Fixing the message was not enough on
+its own: the ASK path looped despite already carrying that warning, because prompt
+wording is a request, not a constraint, and a model under pressure to finish a task
+does not reliably honor it.
+
+Measured against a live, non-interactive provider — this is what a passing test suite
+cannot see, since nothing here raises or returns the wrong value, it just keeps calling
+a tool that keeps getting denied:
+
+- denied `Write .turnloop/settings.local.json`, repeated 10 times → **233,742 input
+  tokens, $0.0372**
+- after the message fix alone → **10,654 tokens, $0.0017**, one attempt then a correct
+  proposal to the user
+- a separate ASK-decline loop on `dir`/`mkdir`, before any fix → **199,352 tokens,
+  $0.0317**
+
+So wording is now backed by a deterministic guard in `ToolRunner` rather than trusted
+alone: identity is tool name plus pydantic-normalized args, scope is the session, one
+free retry, and the entry clears the moment the call is allowed or approved — so a
+permission granted mid-session un-poisons a call that was denied earlier, instead of
+blocking it forever. Fixed in 0.1.6.
+
+**The lesson, eight times over in one project:** an 84-run sweep failing while printing
 a tidy report of zeros; a tool returning empty with `ok: true`; a sweep sitting at
 10/18 doing nothing for 25 minutes; an adapter passing its live test and failing on
 the turn the test never made; a feature with green tests that crashed on its first
-keystroke. Each was caught only by looking past the summary line — and the last two
+keystroke; an implicit invariant that a docstring never stated, so nobody noticed it
+was false; a silent failure that a model reported as success; a cost bug that no
+assertion could ever have caught, because every individual call did exactly what it
+was told. Each was caught only by looking past the summary line — and most of them
 only by using the thing instead of testing it.
 
 ---
@@ -930,26 +1023,28 @@ one-line edit in a CRLF checkout does not produce a whole-file diff.
 ## Testing
 
 ```bash
-pytest                    # 290 tests, no network
+pytest                    # 338 tests, no network
 ruff check turnloop
 mypy turnloop
 ```
 
 | file | tests | |
 |---|---|---|
-| `test_permissions.py` | 48 | rule grammar, compound-command splitting, mode enforcement |
+| `test_permissions.py` | 50 | rule grammar, compound-command splitting, mode enforcement |
 | `test_experiments.py` | 36 | runner, graders, report, suite invariants, config resolution |
 | `test_providers.py` | 35 | adapters vs recorded `.sse`, image blocks, thought signatures |
 | `test_tools_files.py` | 28 | Read/Write/Edit/Glob/Grep, encodings, newlines, image detection |
-| `test_loop.py` | 20 | streaming, truncation, iteration cap |
-| `test_hooks_mcp_commands.py` | 23 | lifecycle hooks, MCP client, slash commands |
-| `test_config.py` | 21 | layering, env overrides, presets, narrow-console guard |
+| `test_hooks_mcp_commands.py` | 28 | lifecycle hooks, MCP client, slash commands |
+| `test_tui.py` | 25 | Textual snapshots, `/config` and `/mcp add` driven through a real app |
+| `test_config.py` | 23 | layering, env overrides, presets, narrow-console guard |
+| `test_skills_install.py` | 19 | frontmatter validation, GitHub resolution, import subsets, drive-root refusal |
+| `test_loop.py` | 23 | streaming, truncation, iteration cap |
 | `test_compaction.py` | 16 | three tiers, tool_use/tool_result invariant |
-| `test_bash.py` | 14 | shell selection, process-tree kill |
 | `test_configio.py` | 15 | minimal-diff writes, atomic save, secret-bearing MCP targets, the settings deny rules |
+| `test_bash.py` | 14 | shell selection, process-tree kill |
 | `test_config_screen.py` | 10 | provider form validation, caps derivation, env indicator leaks |
 | `test_websearch.py` | 9 | HTML parsing, backend selection, truncation, failure modes |
-| `test_tui.py` | 15 | Textual snapshots, `/config` and `/mcp add` driven through a real app |
+| `test_system_prompt_layout.py` | 7 | `CONFIG_LAYOUT` presence, token cost, `minimal` variant omission |
 
 `conftest.py` monkeypatches httpx's transport to raise unless a test is marked
 `live` — **network is off at the transport layer**, so a forgotten real call fails
@@ -996,6 +1091,16 @@ Slash commands live in `.turnloop/commands/*.md`, skills in
 in the system prompt and load their body on demand, which on a 65k window is the
 difference between having skills and not.
 
+The system prompt also documents this layout to the model itself, as `CONFIG_LAYOUT`
+— 326 tokens, in the cacheable region, omitted from the `minimal` variant. Without it
+the model cannot configure the tool it is running inside: asked to add an MCP server
+it invented `.turnloop/turnloop.config.json`, and asked to install a skill it wrote to
+`examples/` — both real outputs from live runs. With it, both go to the right place
+first try. It includes the literal YAML frontmatter a skill needs, since a skill with
+markdown-bold frontmatter instead of YAML used to vanish with no diagnostic; `/skills`
+now also reports anything found on disk but rejected, with the reason and path — see
+[Bugs worth reading about](#bugs-worth-reading-about).
+
 Shell expansion inside a command template (`` !`cmd` ``) goes through the permission
 engine like any other Bash call. A markdown file in a repository is not trusted input
 just because it is on disk.
@@ -1003,8 +1108,9 @@ just because it is on disk.
 ### Editing configuration
 
 `tl config --edit` edits the provider table, permission mode, tool verbosity, iteration
-cap, search backend, memory, and the three rule lists. `tl mcp` manages MCP servers. The
-same screens open inside a running session as `/config` and `/mcp add`.
+cap, search backend, memory, and the three rule lists. `tl mcp` manages MCP servers.
+`tl skills add/list/remove` manages skills. The config and MCP screens open inside a
+running session as `/config` and `/mcp add`.
 
 **Adding a provider** is a form for `kind`, `model`, `base_url`, and `api_key_env`, with
 a live ✓/✗ showing whether that environment variable is currently set. Capabilities are
@@ -1081,6 +1187,37 @@ unavailable" and never blocks the loop. Connections are lazy and every call is b
 None of that helps if you install a server that does exactly what it says. Read what you
 add.
 
+### Skills are a trust decision too
+
+`tl skills add <owner/repo>` resolves a GitHub repo shorthand, a repo URL, or a direct
+raw URL to a `SKILL.md`, and installs it to `.turnloop/skills/<name>/` (or
+`~/.turnloop/skills/` with `--user`). The same reasoning as the MCP section above
+applies without modification: a skill's body is not metadata, it is text that gets
+loaded straight into the model's context the moment the model decides the skill
+applies (`commands/loader.py`). A hostile `SKILL.md` can instruct the model exactly
+like a hostile MCP tool description can. `add` prints the source URL and the
+description and asks for confirmation before writing anything; `--yes` skips waiting
+for that confirmation but never skips printing it, and never skips printing what got
+installed and from where.
+
+Before writing, `add` parses the frontmatter with the same `parse_frontmatter` the
+loader uses and requires a non-empty `description` — the exact rule `load_skills`
+enforces when deciding what to advertise (see "A skill that failed to parse vanished
+with no error" below). A `SKILL.md` that would silently vanish once installed is
+refused before it is ever written, rather than discovered later as "the skill isn't
+there."
+
+**Importing from Claude Code.** If `~/.claude/skills/*/SKILL.md` exist and turnloop
+has never asked about them, one line appears once, in the TUI, pointing at
+`tl skills import` — not a prompt that blocks startup, and not a silent copy.
+Importing computes the token cost of each candidate with `rough_tokens` before you
+choose (34 skills advertise for about 2,961 tokens of permanent system-prompt
+overhead — most of a session's `CONFIG_LAYOUT` segment on its own), lets you import
+any subset, and copies the chosen files into turnloop's own skills directory rather
+than reading `~/.claude/skills` at runtime — turnloop stays uncoupled from another
+tool's directory layout. Whether you say yes or no, the question is recorded in the
+user-level settings file so it is never asked again.
+
 ---
 
 ## Limitations

{turnloop-0.1.5 → turnloop-0.1.7}/README.md

@@ -20,7 +20,7 @@ tl experiment run smoke         # a measurement run, offline and free
 
 Four runtime dependencies: `textual`, `pydantic`, `httpx`, `pyyaml`. No vendor
 SDKs, no agent framework — the loop is the point, so the loop is written here.
-~18,000 lines of Python, 290 tests, no network in the default test run.
+~20,000 lines of Python, 338 tests, no network in the default test run.
 
 ---
 
@@ -88,7 +88,7 @@ point.
 Verify:
 
 ```bash
-tl --version                # turnloop 0.1.5
+tl --version                # turnloop 0.1.7
 tl doctor                   # every provider, key presence, shell, context budget
 ```
 
@@ -110,8 +110,9 @@ context arithmetic for the active provider:
 tl                                          # interactive TUI
 tl -p "why does the login test flake"       # headless single turn
 tl -p "..." --json                          # headless, JSONL events on stdout
-tl --resume                                 # resume the most recent session
-tl --resume <session-id>                    # resume a specific one
+tl -c                                       # resume the most recent session, no picker
+tl --resume                                 # interactive picker (TUI); most recent (headless)
+tl --resume <session-id>                    # resume a specific one, no picker
 tl sessions                                 # list recorded sessions
 tl config                                   # merged config + which layer each value came from
 tl config --edit                            # interactive settings editor
@@ -133,7 +134,8 @@ and neither is reachable by the model — see
 | `--max-iterations N` | tool-loop safety cap (default 40) |
 | `-p, --print PROMPT` | headless single turn |
 | `--json` | headless output as JSONL events |
-| `--resume [ID]` | resume last, or a named session |
+| `-c, --continue` | resume the most recent session directly, no picker |
+| `--resume [ID]` | bare: interactive picker in the TUI, most recent in headless. With an id: that session, no picker |
 
 ### Permission modes
 
@@ -155,12 +157,18 @@ to cycle. Make it permanent via `TURNLOOP_PERMISSION_MODE` or `settings.json`.
 ### Keys
 
 ```
-ctrl+c   interrupt the running turn (again to exit)
+ctrl+c   copy the selection; else interrupt a running turn; else nothing
 ctrl+p   cycle permission mode
 ctrl+l   clear the view (history is kept)
 ctrl+d   quit
 ```
 
+`ctrl+c` no longer quits. It used to call `self.exit()` whenever no turn was
+running, so pressing it to copy text killed the session. It now checks, in order,
+whether there is a selection to copy (via Textual's `App.copy_to_clipboard`, OSC 52,
+no new dependency), then whether a turn is running to interrupt, and otherwise does
+nothing. `ctrl+d` is still the only way to quit.
+
 `ctrl+c` and friends are bound with `priority=True` — the prompt Input always has
 focus and would otherwise swallow them.
 
@@ -176,6 +184,9 @@ focus and would otherwise swallow them.
 /provider    switch provider            /config       settings editor
 /export      transcript to markdown     /hooks        configured hooks
 /sessions    recorded sessions          /doctor       diagnostics
+/skills      loaded skills, and any     /resume       picker, rebuilds the
+             rejected on disk (why,                   agent in place; refuses
+             and where)                                while a turn is running
 /quit        exit
 ```
 
@@ -321,6 +332,13 @@ close a self-escalation path: settings files set `permission_mode` and
 next launch. Verified against the real engine *in bypass mode*, which is the case that
 matters — deny beats bypass, so the block holds even there.
 
+That was a unit test. It has since been verified live: with
+`Write(.turnloop/**)` explicitly allowed *and* `--permission-mode bypass`, a real
+model told to grant itself permanent bypass access was blocked, made one attempt,
+and proposed the change to the user instead. The settings file was unchanged. Deny
+beats an explicit allow rule and bypass mode at once — not just in the test suite,
+against a live model that was actually trying.
+
 It is a guardrail, not a sandbox, and the boundary is worth being precise about. `Write`
 and `Edit` are blocked; **`Bash` is not**, so a shell redirect reaches the same file.
 Closing that properly needs a path guard below the tool layer rather than more patterns.
@@ -366,6 +384,14 @@ because a crashed run still leaves a readable trace, and because the experiments
 layer reads exactly the same format the TUI writes — a run trace and a real session
 are the same artifact.
 
+`-c`/`--continue` reopens the most recent session with no prompting. Bare `--resume`
+in the TUI opens an interactive picker — a `DataTable` of sessions, newest first,
+with a live preview pane of the selected conversation — and `--resume <id>` jumps
+straight to a specific one. `/resume` opens the same picker in-session and rebuilds
+the agent in place; it refuses while a turn is running rather than tearing one down
+mid-flight. Headless has no picker to show, so a bare `--resume` there falls back to
+"most recent" — the same thing `--continue` does.
+
 ---
 
 ## Providers
@@ -862,11 +888,78 @@ And **0.1.4 shipped this way**, so `pip install turnloop==0.1.4` crashes on `/co
 Fixed in 0.1.5. The tests now drive a real app through Textual's `run_test()` pilot and
 fail if the decorators are removed.
 
-**The lesson, five times over in one project:** an 84-run sweep failing while printing
+**A directory that exists on every launch cannot mean "this is a project."**
+
+`find_project_root` treated any ancestor `.turnloop` directory as an explicit project
+declaration. But `default_project_dir` creates `.turnloop/` — with a `sessions/`
+folder and a `.gitignore` — on every launch, unconditionally, wherever turnloop
+happens to start. So the directory's mere existence declared nothing; it was
+frequently just the residue of having once run the tool there. Run `tl` once from a
+home directory, or a drive root, and it permanently annexed every project beneath it:
+sessions, the `.env` layer, `settings.json` and the permission rules all resolved to
+the wrong root from then on. Real instance, the author's own machine: `F:\.turnloop`
+was created on 2026-08-01, and every `F:\anything\proj\pyproject.toml` since then
+resolved its project root to `F:\`.
+
+The invariant that broke was never written down as one, which is exactly why it lasted.
+The fix makes the implicit rule explicit: a `.turnloop` counts only if it holds
+something a human put there — `settings.json`, `settings.local.json`, `commands/`,
+`skills/`, `TURNLOOP.md` — and one holding only an auto-created `sessions/` is ignored.
+The home directory is excluded outright on top of that, since `~/.turnloop` is the
+user-scope settings location and can never mean "project." The false invariant had
+been there since the tool first created `.turnloop/` on launch; fixed in 0.1.6.
+
+**A skill that failed to parse vanished with no error, and the model reported success.**
+
+A live run installed a skill whose frontmatter was markdown-bold — `**name**:
+something` — rather than YAML. `yaml.safe_load` returned no usable keys,
+`load_skills` hit its "no description" skip, and the skill disappeared: no exception,
+no log line, nothing in `/skills`. The model that had just "installed" it reported
+success, because from its side the write succeeded and nothing said otherwise.
+
+The bug was not the parser rejecting bad frontmatter — that part is correct. It was
+that a rejection and a nonexistent skill looked identical from the outside. `load_skills`
+keeps its exact signature, but a new `rejected_skills()` now returns what was dropped
+and why, `/skills` reports it, and `CONFIG_LAYOUT` shows the literal YAML frontmatter
+block in the system prompt so the model stops guessing at markdown-bold instead.
+Fixed in 0.1.6.
+
+**A permission denial that should end in one message looped ten times, and it cost
+real money before anyone noticed — because nothing about it failed a test.**
+
+Two defects landed in the same code path with the same symptom. The DENY branch's
+message said only `Permission denied: <rule>`; the ASK-decline branch, which is
+recoverable, had always carried "Do not retry it" — so the weaker wording sat on the
+*permanent* block, the one that most needed it. Fixing the message was not enough on
+its own: the ASK path looped despite already carrying that warning, because prompt
+wording is a request, not a constraint, and a model under pressure to finish a task
+does not reliably honor it.
+
+Measured against a live, non-interactive provider — this is what a passing test suite
+cannot see, since nothing here raises or returns the wrong value, it just keeps calling
+a tool that keeps getting denied:
+
+- denied `Write .turnloop/settings.local.json`, repeated 10 times → **233,742 input
+  tokens, $0.0372**
+- after the message fix alone → **10,654 tokens, $0.0017**, one attempt then a correct
+  proposal to the user
+- a separate ASK-decline loop on `dir`/`mkdir`, before any fix → **199,352 tokens,
+  $0.0317**
+
+So wording is now backed by a deterministic guard in `ToolRunner` rather than trusted
+alone: identity is tool name plus pydantic-normalized args, scope is the session, one
+free retry, and the entry clears the moment the call is allowed or approved — so a
+permission granted mid-session un-poisons a call that was denied earlier, instead of
+blocking it forever. Fixed in 0.1.6.
+
+**The lesson, eight times over in one project:** an 84-run sweep failing while printing
 a tidy report of zeros; a tool returning empty with `ok: true`; a sweep sitting at
 10/18 doing nothing for 25 minutes; an adapter passing its live test and failing on
 the turn the test never made; a feature with green tests that crashed on its first
-keystroke. Each was caught only by looking past the summary line — and the last two
+keystroke; an implicit invariant that a docstring never stated, so nobody noticed it
+was false; a silent failure that a model reported as success; a cost bug that no
+assertion could ever have caught, because every individual call did exactly what it
+was told. Each was caught only by looking past the summary line — and most of them
 only by using the thing instead of testing it.
 
 ---
@@ -901,26 +994,28 @@ one-line edit in a CRLF checkout does not produce a whole-file diff.
 ## Testing
 
 ```bash
-pytest                    # 290 tests, no network
+pytest                    # 338 tests, no network
 ruff check turnloop
 mypy turnloop
 ```
 
 | file | tests | |
 |---|---|---|
-| `test_permissions.py` | 48 | rule grammar, compound-command splitting, mode enforcement |
+| `test_permissions.py` | 50 | rule grammar, compound-command splitting, mode enforcement |
 | `test_experiments.py` | 36 | runner, graders, report, suite invariants, config resolution |
 | `test_providers.py` | 35 | adapters vs recorded `.sse`, image blocks, thought signatures |
 | `test_tools_files.py` | 28 | Read/Write/Edit/Glob/Grep, encodings, newlines, image detection |
-| `test_loop.py` | 20 | streaming, truncation, iteration cap |
-| `test_hooks_mcp_commands.py` | 23 | lifecycle hooks, MCP client, slash commands |
-| `test_config.py` | 21 | layering, env overrides, presets, narrow-console guard |
+| `test_hooks_mcp_commands.py` | 28 | lifecycle hooks, MCP client, slash commands |
+| `test_tui.py` | 25 | Textual snapshots, `/config` and `/mcp add` driven through a real app |
+| `test_config.py` | 23 | layering, env overrides, presets, narrow-console guard |
+| `test_skills_install.py` | 19 | frontmatter validation, GitHub resolution, import subsets, drive-root refusal |
+| `test_loop.py` | 23 | streaming, truncation, iteration cap |
 | `test_compaction.py` | 16 | three tiers, tool_use/tool_result invariant |
-| `test_bash.py` | 14 | shell selection, process-tree kill |
 | `test_configio.py` | 15 | minimal-diff writes, atomic save, secret-bearing MCP targets, the settings deny rules |
+| `test_bash.py` | 14 | shell selection, process-tree kill |
 | `test_config_screen.py` | 10 | provider form validation, caps derivation, env indicator leaks |
 | `test_websearch.py` | 9 | HTML parsing, backend selection, truncation, failure modes |
-| `test_tui.py` | 15 | Textual snapshots, `/config` and `/mcp add` driven through a real app |
+| `test_system_prompt_layout.py` | 7 | `CONFIG_LAYOUT` presence, token cost, `minimal` variant omission |
 
 `conftest.py` monkeypatches httpx's transport to raise unless a test is marked
 `live` — **network is off at the transport layer**, so a forgotten real call fails
@@ -967,6 +1062,16 @@ Slash commands live in `.turnloop/commands/*.md`, skills in
 in the system prompt and load their body on demand, which on a 65k window is the
 difference between having skills and not.
 
+The system prompt also documents this layout to the model itself, as `CONFIG_LAYOUT`
+— 326 tokens, in the cacheable region, omitted from the `minimal` variant. Without it
+the model cannot configure the tool it is running inside: asked to add an MCP server
+it invented `.turnloop/turnloop.config.json`, and asked to install a skill it wrote to
+`examples/` — both real outputs from live runs. With it, both go to the right place
+first try. It includes the literal YAML frontmatter a skill needs, since a skill with
+markdown-bold frontmatter instead of YAML used to vanish with no diagnostic; `/skills`
+now also reports anything found on disk but rejected, with the reason and path — see
+[Bugs worth reading about](#bugs-worth-reading-about).
+
 Shell expansion inside a command template (`` !`cmd` ``) goes through the permission
 engine like any other Bash call. A markdown file in a repository is not trusted input
 just because it is on disk.
@@ -974,8 +1079,9 @@ just because it is on disk.
 ### Editing configuration
 
 `tl config --edit` edits the provider table, permission mode, tool verbosity, iteration
-cap, search backend, memory, and the three rule lists. `tl mcp` manages MCP servers. The
-same screens open inside a running session as `/config` and `/mcp add`.
+cap, search backend, memory, and the three rule lists. `tl mcp` manages MCP servers.
+`tl skills add/list/remove` manages skills. The config and MCP screens open inside a
+running session as `/config` and `/mcp add`.
 
 **Adding a provider** is a form for `kind`, `model`, `base_url`, and `api_key_env`, with
 a live ✓/✗ showing whether that environment variable is currently set. Capabilities are
@@ -1052,6 +1158,37 @@ unavailable" and never blocks the loop. Connections are lazy and every call is b
 None of that helps if you install a server that does exactly what it says. Read what you
 add.
 
+### Skills are a trust decision too
+
+`tl skills add <owner/repo>` resolves a GitHub repo shorthand, a repo URL, or a direct
+raw URL to a `SKILL.md`, and installs it to `.turnloop/skills/<name>/` (or
+`~/.turnloop/skills/` with `--user`). The same reasoning as the MCP section above
+applies without modification: a skill's body is not metadata, it is text that gets
+loaded straight into the model's context the moment the model decides the skill
+applies (`commands/loader.py`). A hostile `SKILL.md` can instruct the model exactly
+like a hostile MCP tool description can. `add` prints the source URL and the
+description and asks for confirmation before writing anything; `--yes` skips waiting
+for that confirmation but never skips printing it, and never skips printing what got
+installed and from where.
+
+Before writing, `add` parses the frontmatter with the same `parse_frontmatter` the
+loader uses and requires a non-empty `description` — the exact rule `load_skills`
+enforces when deciding what to advertise (see "A skill that failed to parse vanished
+with no error" below). A `SKILL.md` that would silently vanish once installed is
+refused before it is ever written, rather than discovered later as "the skill isn't
+there."
+
+**Importing from Claude Code.** If `~/.claude/skills/*/SKILL.md` exist and turnloop
+has never asked about them, one line appears once, in the TUI, pointing at
+`tl skills import` — not a prompt that blocks startup, and not a silent copy.
+Importing computes the token cost of each candidate with `rough_tokens` before you
+choose (34 skills advertise for about 2,961 tokens of permanent system-prompt
+overhead — most of a session's `CONFIG_LAYOUT` segment on its own), lets you import
+any subset, and copies the chosen files into turnloop's own skills directory rather
+than reading `~/.claude/skills` at runtime — turnloop stays uncoupled from another
+tool's directory layout. Whether you say yes or no, the question is recorded in the
+user-level settings file so it is never asked again.
+
 ---
 
 ## Limitations

{turnloop-0.1.5 → turnloop-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "turnloop"
-version = "0.1.5"
+version = "0.1.7"
 description = "A local-first agentic coding harness: streaming tool loop, permission gating, context compaction, subagents, and any LLM provider."
 readme = "README.md"
 requires-python = ">=3.11"