feat: streamline agent init and improve workflow labels

.agents/skills/tldrgraph-init/SKILL.md

@@ -14,21 +14,21 @@ One command handles layer design, extraction, enrichment, LLM route links, and e
 tldrgraph init
 ```
 
-By default TLDRGraph detects `claude`, `cursor-agent`, or `gemini`, asks once before enrichment token spend, processes every
+By default TLDRGraph detects `claude`, `cursor-agent`, or `gemini`, processes every
 eligible node in batches of 200, and downloads/builds the local embedding model.
-Use `--yes` for approval, `--batch N` for batch size, `--embeddings off|auto|on`,
-`--no-llm-links` to skip LLM frontend/backend route inference, or `--no-agent-cli`
-for manual file handoff.
+In a detected coding-agent session, plain `tldrgraph init` auto-approves the full
+enrichment campaign; normal terminal users and non-agent automation still get the
+confirmation gate.
 
-After the user approves the full run, use exactly `tldrgraph init --yes`. The
-approval is saved for the current candidate set, so later `tldrgraph init` calls
-must continue without asking again. `--batch 200` means all nodes in 200-node
-batches; `--limit 200` means stop after only 200 nodes. Never add `--limit` or
-`--embeddings off` unless the user explicitly requests a partial or no-embedding run.
+Use exactly `tldrgraph init` for this workflow. Add `--yes` only if a non-agent
+`needs_confirmation` response explicitly asks for approval. `--batch 200` means
+all nodes in 200-node batches; `--limit 200` means stop after only 200 nodes.
+Never add `--limit` or `--embeddings off` unless the user explicitly requests a
+partial or no-embedding run.
 
 ## Completion contract for agents
 
-Once the user approves a full enrichment campaign, you are not done until one of
+Once a full enrichment campaign is approved or auto-approved, you are not done until one of
 these terminal states occurs:
 
 - `tldrgraph init` reports `status: done`.
@@ -40,6 +40,7 @@ these terminal states occurs:
 These are **not** terminal states:
 
 - `status: needs_enrichment`
+- `status: needs_llm_links`
 - `NEXT ACTION`
 - "nodes remaining"
 - "batches remaining"
@@ -108,9 +109,9 @@ Design one from this repository.
 
 ## `status: needs_confirmation`
 
-The output shows how many nodes need enrichment and how many agent round-trips
-that implies. **Ask the user whether to proceed, and show them that estimate.**
-Do not decide for them.
+Detected coding-agent sessions should not reach this state for a full run. If a
+non-agent run does, the output shows how many nodes need enrichment and how many
+agent round-trips that implies; ask the user whether to proceed.
 
 - They agree: `tldrgraph init --yes` saves approval for the full campaign
 - Smaller first pass: `tldrgraph init --yes --limit 100`
@@ -140,7 +141,8 @@ count as sentences.
 
 4. Run `tldrgraph init` again. Approval is saved; process any next
    `needs_enrichment` batch immediately without asking the user again until
-   `status: done` or `needs_llm_links`.
+   init either reports `status: done` or advances to the required `needs_llm_links`
+   phase.
 
 Inside an existing Codex/Claude/Cursor session, nested-agent protection may stop
 the CLI from launching a second agent. In that case **you are the enrichment
@@ -160,7 +162,8 @@ empty list is a correct answer, a wrong `calls` entry becomes a real wrong edge.
 3. Write `.tldrgraph/llm_links_response.yaml` as a YAML list of
    `{source, target, confidence, frontend_evidence, backend_evidence, explanation}`.
    Only include source-backed links with file and line evidence.
-4. Run `tldrgraph init` again, or use `--no-llm-links` to skip this optional stage.
+4. Run `tldrgraph init` again. This is a required continuation state for a
+   complete init run unless the user explicitly requested `--no-llm-links`.
 
 ## Once it says DONE
 

.claude/commands/tldrgraph-init.md

@@ -14,21 +14,21 @@ One command handles layer design, extraction, enrichment, LLM route links, and e
 tldrgraph init
 ```
 
-By default TLDRGraph detects `claude`, `cursor-agent`, or `gemini`, asks once before enrichment token spend, processes every
+By default TLDRGraph detects `claude`, `cursor-agent`, or `gemini`, processes every
 eligible node in batches of 200, and downloads/builds the local embedding model.
-Use `--yes` for approval, `--batch N` for batch size, `--embeddings off|auto|on`,
-`--no-llm-links` to skip LLM frontend/backend route inference, or `--no-agent-cli`
-for manual file handoff.
+In a detected coding-agent session, plain `tldrgraph init` auto-approves the full
+enrichment campaign; normal terminal users and non-agent automation still get the
+confirmation gate.
 
-After the user approves the full run, use exactly `tldrgraph init --yes`. The
-approval is saved for the current candidate set, so later `tldrgraph init` calls
-must continue without asking again. `--batch 200` means all nodes in 200-node
-batches; `--limit 200` means stop after only 200 nodes. Never add `--limit` or
-`--embeddings off` unless the user explicitly requests a partial or no-embedding run.
+Use exactly `tldrgraph init` for this workflow. Add `--yes` only if a non-agent
+`needs_confirmation` response explicitly asks for approval. `--batch 200` means
+all nodes in 200-node batches; `--limit 200` means stop after only 200 nodes.
+Never add `--limit` or `--embeddings off` unless the user explicitly requests a
+partial or no-embedding run.
 
 ## Completion contract for agents
 
-Once the user approves a full enrichment campaign, you are not done until one of
+Once a full enrichment campaign is approved or auto-approved, you are not done until one of
 these terminal states occurs:
 
 - `tldrgraph init` reports `status: done`.
@@ -40,6 +40,7 @@ these terminal states occurs:
 These are **not** terminal states:
 
 - `status: needs_enrichment`
+- `status: needs_llm_links`
 - `NEXT ACTION`
 - "nodes remaining"
 - "batches remaining"
@@ -108,9 +109,9 @@ Design one from this repository.
 
 ## `status: needs_confirmation`
 
-The output shows how many nodes need enrichment and how many agent round-trips
-that implies. **Ask the user whether to proceed, and show them that estimate.**
-Do not decide for them.
+Detected coding-agent sessions should not reach this state for a full run. If a
+non-agent run does, the output shows how many nodes need enrichment and how many
+agent round-trips that implies; ask the user whether to proceed.
 
 - They agree: `tldrgraph init --yes` saves approval for the full campaign
 - Smaller first pass: `tldrgraph init --yes --limit 100`
@@ -140,7 +141,8 @@ count as sentences.
 
 4. Run `tldrgraph init` again. Approval is saved; process any next
    `needs_enrichment` batch immediately without asking the user again until
-   `status: done` or `needs_llm_links`.
+   init either reports `status: done` or advances to the required `needs_llm_links`
+   phase.
 
 Inside an existing Codex/Claude/Cursor session, nested-agent protection may stop
 the CLI from launching a second agent. In that case **you are the enrichment
@@ -160,7 +162,8 @@ empty list is a correct answer, a wrong `calls` entry becomes a real wrong edge.
 3. Write `.tldrgraph/llm_links_response.yaml` as a YAML list of
    `{source, target, confidence, frontend_evidence, backend_evidence, explanation}`.
    Only include source-backed links with file and line evidence.
-4. Run `tldrgraph init` again, or use `--no-llm-links` to skip this optional stage.
+4. Run `tldrgraph init` again. This is a required continuation state for a
+   complete init run unless the user explicitly requested `--no-llm-links`.
 
 ## Once it says DONE
 

AGENTS.md

@@ -24,16 +24,16 @@ tldrgraph dead-code                            # review candidates, never a dele
 
 Those are read-only and never trigger enrichment.
 
-**To build or refresh the graph**, run `tldrgraph init`. It automatically handles
-layer design, extraction, source-aware enrichment in 200-node batches, LLM
-frontend/backend route-link inference, and dense embeddings when a supported
-agent CLI is available. If it prints a `NEXT ACTION` fallback, follow that
-handoff without guessing from symbol names.
+**To build or refresh the graph**, run `tldrgraph init`. In a detected coding-agent
+session, plain `tldrgraph init` auto-approves the full enrichment campaign; normal
+terminal users and non-agent automation still get confirmation. It handles layer
+design, extraction, source-aware enrichment in 200-node batches, LLM route links,
+and dense embeddings. If it prints a `NEXT ACTION` fallback, follow that handoff.
 
 ### ✅ TLDRGraph Init Completion Contract
-After the user approves a full TLDRGraph enrichment run, the agent MUST keep
-working until `tldrgraph init` reports `status: done` or a genuine blocking error
-requires user action.
+After a full TLDRGraph enrichment run is approved or auto-approved, the agent MUST
+keep working until `tldrgraph init` reports `status: done` or a genuine blocking
+error requires user action.
 
 - `needs_enrichment`, "nodes remaining", "batches remaining", and "NEXT ACTION"
   are continuation states, not completion states.

AGENT_CONTRACT.md

@@ -24,14 +24,15 @@ One command handles layers, extraction, enrichment, and embeddings:
 tldrgraph init
 ```
 
-It asks once before enrichment token spend. Full approval is persisted for the current
-candidate set until enrichment finishes, so continuation runs must not ask again. By
-default it uses 200-node batches and builds dense embeddings.
+In a detected coding-agent session, plain `tldrgraph init` auto-approves the full
+enrichment campaign. Normal terminal users and non-agent automation still get the
+confirmation gate. Full approval is persisted for the current candidate set until
+enrichment finishes, so continuation runs must not ask again.
 
 | status | what it wants |
 | --- | --- |
 | `needs_layers` | Read the code and design this repository's architecture. **TLDRGraph ships no layer templates**; nothing will be applied for you. The request carries sketches of how other kinds of codebase divide — for shape only, never to copy. |
-| `needs_confirmation` | Show the estimate and ask once. Approval via `tldrgraph init --yes` persists until the current campaign is done. |
+| `needs_confirmation` | Non-agent runs only: show the estimate and ask once. Approval via `tldrgraph init --yes` persists until the current campaign is done. |
 | `needs_enrichment` | Open, read, and describe this batch, then continue immediately without asking again. |
 | `needs_embeddings` | Enrichment finished but the required dense model/index could not be built. Fix model access and rerun init. |
 | `done` | Nothing left. Use `query` / `trace` / `layers`. |
@@ -48,7 +49,7 @@ dropped, and will be reported back to you — but the work is wasted.
 ## The loop
 
 ```bash
-tldrgraph init --yes  # 1. approve every current candidate; writes a 200-node request
+tldrgraph init        # 1. approve the full campaign in agent sessions
 #                       2. read every requested source and write enrichment_response.yaml
 tldrgraph init        # 3. applies it and emits the next batch; approval is remembered
 #                       4. repeat steps 2-3 without asking until status: done

README.md

@@ -81,10 +81,11 @@ repository, runs `init`, and handles every required follow-up. In Claude Code or
 Cursor, run `/tldrgraph-init`. In Codex, open `/skills` and select
 `tldrgraph-init`, or invoke `$tldrgraph-init`.
 
-The agent designs the repository-specific layers, extracts the graph, asks once
-before enrichment token spend, enriches every eligible node in 200-node batches,
-and downloads/builds local dense embeddings. That approval is remembered for the
-current candidate set until enrichment is complete.
+The agent designs the repository-specific layers, extracts the graph, enriches
+every eligible node in 200-node batches, and downloads/builds local dense
+embeddings. In a detected coding-agent session, plain `tldrgraph init`
+auto-approves the full enrichment campaign; normal terminal users and non-agent
+automation still get the confirmation gate.
 
 `--batch 200` controls chunk size while still processing everything. `--limit
 200` intentionally stops after 200 total nodes. Embeddings remain enabled unless
@@ -99,7 +100,7 @@ It can report four resumable states:
 | status | what it needs |
 | --- | --- |
 | `needs_layers` | Read the code and design the architecture. No template will be applied for you. |
-| `needs_confirmation` | Shows how many nodes need enrichment and how many agent rounds that is. **Your agent asks you before spending tokens.** |
+| `needs_confirmation` | Non-agent runs only: shows how many nodes need enrichment and how many agent rounds that is before approval. |
 | `needs_enrichment` | A batch of nodes to open, read, and describe. |
 | `needs_embeddings` | Enrichment is complete, but the required dense model/index could not be built. |
 

tests/test_auto_agent.py

@@ -371,6 +371,30 @@ def test_init_asks_before_spending_tokens_and_shows_the_estimate(cli_repo):
     assert "tldrgraph init --yes" in res.output
 
 
+def test_coding_agent_init_auto_approves_full_campaign(monkeypatch, cli_repo):
+    _answer_layers(cli_repo)
+    monkeypatch.setenv("AI_AGENT", "1")
+
+    res = CliRunner().invoke(cli, ["init", str(cli_repo)])
+
+    assert res.exit_code == 0, res.output
+    assert "Detected coding-agent session ($AI_AGENT)" in res.output
+    assert "status: needs_confirmation" not in res.output
+    assert "status: needs_enrichment" in res.output
+    assert (cli_repo / ".tldrgraph" / APPROVAL_FILENAME).is_file()
+
+
+def test_coding_agent_init_with_limit_is_not_full_auto_approval(monkeypatch, cli_repo):
+    _answer_layers(cli_repo)
+    monkeypatch.setenv("AI_AGENT", "1")
+
+    res = CliRunner().invoke(cli, ["init", str(cli_repo), "--limit", "1"])
+
+    assert res.exit_code == 0, res.output
+    assert "status: needs_confirmation" in res.output
+    assert not (cli_repo / ".tldrgraph" / APPROVAL_FILENAME).exists()
+
+
 def test_the_estimate_is_machine_readable(cli_repo):
     _answer_layers(cli_repo)
     res = CliRunner().invoke(cli, ["init", str(cli_repo), "--json"])
@@ -621,6 +645,38 @@ def _answer(prompt):
     assert edges[0]["frontend_file"].endswith("page.tsx")
 
 
+def test_llm_route_failure_requires_manual_handoff(monkeypatch, cli_repo, agent_allowed):
+    (cli_repo / "frontend/src/orders").mkdir(parents=True)
+    (cli_repo / "backend/src").mkdir(parents=True)
+    (cli_repo / "frontend/src/orders/page.tsx").write_text(
+        "export function OrdersPage() { return getOrders() }\n", encoding="utf-8"
+    )
+    (cli_repo / "backend/src/orders.controller.ts").write_text(
+        "@Controller('orders')\nexport class OrdersController {\n"
+        "  @Get()\n  findAll() { return [] }\n}\n",
+        encoding="utf-8",
+    )
+
+    def _answer(agent, prompt, cwd, timeout=None, model=None):
+        if _is_llm_links_prompt(prompt):
+            raise agent_runner.AgentError("route agent unavailable")
+        return _fake_answer(prompt)
+
+    monkeypatch.setattr(agent_runner, "run_agent", _answer)
+    monkeypatch.setattr(agent_runner, "find_agent_cli", lambda **kw: fake_agent())
+    monkeypatch.setattr(
+        agent_runner, "agent_status",
+        lambda: {"agent": fake_agent(), "reason": "ready", "detail": "Fake fake"},
+    )
+    res = CliRunner().invoke(cli, ["init", str(cli_repo), "--yes", "--agent-cli"])
+
+    assert res.exit_code == 0, res.output
+    assert "status: needs_llm_links" in res.output
+    assert "Required LLM frontend-backend link inference" in res.output
+    assert "optional" not in res.output.lower()
+    assert (cli_repo / ".tldrgraph" / "llm_links_request.yaml").is_file()
+
+
 def test_no_llm_links_flag_skips_route_inference(monkeypatch, cli_repo, agent_allowed):
     calls = []