---
description: "nebu-ctx: use the public 5-tool MCP surface instead of native or private tool names"
globs: **/*
alwaysApply: true
---

# nebu-ctx — Context Engineering Layer
<!-- nebu-ctx-rules-v11 -->

Use only the public nebu-ctx MCP surface in guidance.

## Tool Mapping

| PREFER | OVER | Why |
|--------|------|-----|
| `ctx_read(target="file"|"files"|"symbol"|"outline"|"archive", ...)` | `Read` | Public cached read API for files, symbols, outlines, and archives |
| `ctx_shell` | `Shell` | Pattern-based compression for git, npm, cargo, docker, tsc |
| `ctx_search(mode="regex"|"semantic", ...)` | `Grep` | Compact regex and semantic search results |
| `ctx_tree` | `ls`, `find` | Compact directory maps with file counts |
| `ctx(domain="memory"|"context"|"graph"|"analytics"|"agents"|"inspect", action="...")` | private `ctx_*` implementation details | Stable public gateway for advanced operations |

## Public Contract

- `ctx_read` targets: `file`, `files`, `symbol`, `outline`, `archive`
- `ctx_search` modes: `regex`, `semantic`
- `ctx` domains: `memory`, `context`, `graph`, `analytics`, `agents`, `inspect`

Examples:

```text
ctx_read(target="file", path="src/main.rs")
ctx_read(target="symbol", name="main", file="src/main.rs")
ctx_read(target="outline", path="src/lib.rs")
ctx_search(mode="regex", pattern="pub fn", path="src/")
ctx_search(mode="semantic", query="session state persistence", path="src/")
ctx(domain="memory", action="recall", query="session state decisions")
```

Use private `ctx_*` names only when documenting nebu-ctx internals. Public-facing guidance should stick to the 5 tools above.

## File Editing

Use native Edit/StrReplace/Write/Delete tools for mutations.

## Session Management

- `ctx(domain="memory", action="save"|"recall"|"store"|"consolidate")`
- `ctx(domain="context", action="overview"|"compress")`
- `ctx(domain="graph", action="...")`
- `ctx(domain="analytics", action="...")`
- `ctx(domain="agents", action="...")`
- `ctx(domain="inspect", action="...")`

## Proactive Tools

Use without being asked:
- `ctx(domain="context", action="compress")` — when context grows large
- `ctx(domain="analytics", action="report")` — when analytics are needed
- `ctx(domain="context", action="overview", task="...")` — at session start
- `ctx(domain="memory", action="save"|"store"|"recall")` — when session state or durable facts should persist

## Write, Delete, Glob

These have no nebu-ctx equivalent — use them normally.

## CRP v2 — Compact Response Protocol

Every token costs money. This applies to input, output, AND thinking tokens.

### Thinking Reduction (saves 30-60% thinking tokens)

1. Parse task first, then act. Don't explore when you already know the answer.
2. One hypothesis, test it. Don't enumerate 5 approaches — pick the most likely, try it.
3. Stop thinking when you have the answer.
4. Use structured context from the public nebu-ctx tools before re-reading files.
5. File ref tracking: F1=auth.ts means F1 everywhere in this session.

### Output Reduction (saves 50-80% output tokens)

1. NO prose. Just code and results.
2. NO echoing content that was just read.
3. Summarize tool results: 1 line max.
4. Show edits only — not surrounding unchanged code.
5. Batch tool calls. One message, multiple calls.
6. Never ask "shall I proceed?" — just do it.
7. Bullets > paragraphs. Tables > lists.

### Compact Notation

- `F:path` — reading file
- `+file` = created, `~file` = modified, `!file` = error
- `->` for results: "Built -> 18 pages, 0 errors"

## Scope Guard

Only recommend `ctx_read`, `ctx_search`, `ctx_tree`, `ctx_shell`, and `ctx` in public-facing rules.
<!-- /lean-ctx -->
