Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
110 commits
Select commit Hold shift + click to select a range
144c7c7
vendor: rebrand upstream 0.37.1 (c11da4fbd)
elkaix Aug 19, 2026
bd8349b
feat(sync): checkpoint 2026-08 reconciliation and branded CLI/TUI ref…
elkaix Aug 20, 2026
0b40bdf
chore: merge rebranded upstream 144c7c7d8 (kimi-code @ c11da4fbd, 0.3…
elkaix Aug 20, 2026
e8c67fe
feat(app)!: remove legacy session migration machinery
elkaix Aug 20, 2026
ec4dbda
refactor(agent-core-v2)!: retire legacy-named session and auth modules
elkaix Aug 20, 2026
f294dbd
refactor(gateway): rename the server package
elkaix Aug 20, 2026
89ad656
feat(workflow): complete session interfaces
elkaix Aug 20, 2026
141e198
chore(repo): align release safeguards
elkaix Aug 20, 2026
501c877
fix: restore upstream TUI and ACP parity regressions
elkaix Aug 20, 2026
e04d774
refactor(plugins): remove Kimi marketplace default, trusted hostnames…
elkaix Aug 20, 2026
d1e2cab
refactor(app): repoint telemetry to Pythinker and remove Kimi update/…
elkaix Aug 20, 2026
a4531a5
chore(docs): sweep Kimi doc links and extend check-managed with an id…
elkaix Aug 20, 2026
565ce2b
chore: add changeset and fix unused parameter after update-check removal
elkaix Aug 20, 2026
6b3e9bb
test: align native-stage and gateway marketplace tests with disabled …
elkaix Aug 20, 2026
e858dd4
test: narrow fetch call URLs explicitly in gateway marketplace test
elkaix Aug 20, 2026
d2d7a13
fix(vscode): repair host-SDK regressions and restore real SDK types
elkaix Aug 20, 2026
9948a83
feat(web): port reference design tokens, dock primitives, and i18n keys
elkaix Aug 20, 2026
8bcedee
feat(web): port reference chat dock — workbar pills and dock panels
elkaix Aug 20, 2026
8084cdb
feat(web): port reference composer internals and status panel
elkaix Aug 20, 2026
e11b447
fix(web): split workflow enable confirm into title and message
elkaix Aug 20, 2026
bd27fc2
fix(web): dedupe dynamicWorkflowIndex after rebase merge
elkaix Aug 20, 2026
152e8ad
feat(web): make the composer workflow chip agent-driven
elkaix Aug 20, 2026
35da551
docs(web): changeset and agent-guide notes for the composer port
elkaix Aug 20, 2026
9959b19
vendor: rebrand upstream 0.37.2 (ca87c58e6)
elkaix Aug 20, 2026
7bb024c
Merge branch 'vendor/upstream' into sync/upstream-0.37.2
elkaix Aug 20, 2026
c5a106c
test(mcp): wait for confirmed stdio close
elkaix Aug 19, 2026
117f1f8
chore(sync): reconcile manifests, test snapshots, and changeset after…
elkaix Aug 20, 2026
ce837a8
fix(web): resolve lint errors in composer and conversation pane
elkaix Aug 20, 2026
6aa4e42
refactor: rename kaos OS-abstraction package to pyaos
elkaix Aug 20, 2026
bb2e82e
feat(web): parity wave 1 — Schibsted Grotesk font, mention pills, sma…
elkaix Aug 20, 2026
7467077
feat(web): parity wave 2a — per-tool call renderers
elkaix Aug 20, 2026
1bb6d01
feat(web): parity wave 2b — turn chrome
elkaix Aug 20, 2026
679305e
feat(web): parity wave 2c — transcript search and media lightbox
elkaix Aug 20, 2026
d7e23e1
refactor(web): rename kw-icon class family to ui-icon
elkaix Aug 20, 2026
e1766e8
feat(web): parity wave 3 — sidebar and session management
elkaix Aug 20, 2026
6de7748
feat(web): parity wave 4a — settings providers tab and about section
elkaix Aug 20, 2026
39878d7
feat(web): parity wave 4b — session admin view, terminal tabs, list p…
elkaix Aug 20, 2026
0544bf4
docs(web): changesets for the parity waves
elkaix Aug 20, 2026
b19df43
docs(web): note the in-repo vendor bundle path for design parity work
elkaix Aug 20, 2026
f7d8ed2
fix(web): drop the last blue-tinted dark values for neutral grey
elkaix Aug 20, 2026
2096257
fix(web): drop the dev backend pill and version-prefixed backend label
elkaix Aug 20, 2026
6caeab4
feat(core-v2): add execEnv shellPathBridge for git-bash path resolution
elkaix Aug 21, 2026
327d089
feat(core-v2): add generic keyedResource lease-pool primitive
elkaix Aug 21, 2026
7eb49d8
feat(core-v2): emit Workspace Created/Updated/Deleted events
elkaix Aug 21, 2026
8b804de
feat(core-v2): add AgentModel/AgentEffect framework and AgentContext …
elkaix Aug 21, 2026
2183963
feat(core-v2): move token counting onto a session-scoped feature
elkaix Aug 21, 2026
6735541
feat(core-v2): move usage onto a session-scoped feature with cache probe
elkaix Aug 21, 2026
0e5f349
refactor(core-v2): move goal domain onto the Feature seam
elkaix Aug 21, 2026
d4695b7
feat(core-v2): add todo feature over the agent-model seam
elkaix Aug 21, 2026
7616dcc
feat(core-v2): add forked conversation context to subagent runs
elkaix Aug 21, 2026
f7ff724
feat(core-v2): wire fork parameter through the agent tools
elkaix Aug 21, 2026
2a8d34a
refactor(core-v2): rewire engine consumers to session-scoped services
elkaix Aug 21, 2026
e4ca224
test(core-v2): update tests for session-scoped feature rewire
elkaix Aug 21, 2026
423f112
feat(pyaos): add git-bash shell path bridge
elkaix Aug 21, 2026
4387026
feat(oauth): add pythinker region resolution
elkaix Aug 21, 2026
fc8dee3
fix(agent-core): route git-bash paths through the shell path bridge
elkaix Aug 21, 2026
0589695
fix(agent-core): drain background-task output writes before session c…
elkaix Aug 21, 2026
e5dab43
fix(agent-core): await proactive MCP OAuth refreshes during shutdown
elkaix Aug 21, 2026
935747c
fix(agent-core): stop compaction shrinking budget on safety-filtered …
elkaix Aug 21, 2026
3e9b18e
feat(klient): forward login region option through the wire contract
elkaix Aug 21, 2026
e58e2ef
refactor(klient): repoint facades at session-scoped v2 services
elkaix Aug 21, 2026
d7a6896
feat(sdk): add login region option and track v2 engine rewiring
elkaix Aug 21, 2026
c30436b
fix(kosong): fail fast on safety-filtered empty responses
elkaix Aug 21, 2026
6b1b95d
fix(minidb): guard lock-retirement close with the writer-op lease
elkaix Aug 21, 2026
21ab355
feat(protocol): add config.persist_blocked error code
elkaix Aug 21, 2026
0c4e45a
fix(transcript): factor taskId into origin equality checks
elkaix Aug 21, 2026
9efc83c
fix(acp): drain append-log retirements and log closes on shutdown
elkaix Aug 21, 2026
f714945
feat(telemetry): support region-aware flush endpoint
elkaix Aug 21, 2026
7cd1ad7
feat(pi-tui): add jump-to-bottom control for scrolled viewports
elkaix Aug 21, 2026
cfb4fee
refactor(gateway): repoint transcript/status at session-scoped v2 ser…
elkaix Aug 21, 2026
2d38fe3
feat(gateway): broadcast session-archived and workspace lifecycle events
elkaix Aug 21, 2026
3a7d6bf
test(gateway): cover workspace grouping, lifecycle broadcasts, rewire
elkaix Aug 21, 2026
7e620eb
feat(web): stream transcripts and provider management over the daemon…
elkaix Aug 21, 2026
b9e81d7
feat(web): redesign transcript — per-tool cards, folds, search, media
elkaix Aug 21, 2026
7df1cee
feat(web): composer running-work pills, model picker and tool meta
elkaix Aug 21, 2026
bce60f2
feat(web): session management — pins, admin table, grouped sidebar
elkaix Aug 21, 2026
05afdb2
feat(web): settings — add-provider flow and per-provider model list
elkaix Aug 21, 2026
cdf7418
feat(web): restyle background-task notifications as light notices
elkaix Aug 21, 2026
1cf220c
feat(web): improve mobile shell UI styling
elkaix Aug 21, 2026
65a496d
feat(web): shared app shell, theme tokens and design-system view
elkaix Aug 21, 2026
f465b48
test(web): cover transcript, sessions, settings, daemon and helpers
elkaix Aug 21, 2026
b9b8231
feat(cli): region-aware login and derived endpoint resolution
elkaix Aug 21, 2026
b2e485e
fix(cli): partition client-config cache and base URL by region
elkaix Aug 21, 2026
eafcdf9
feat(tui): drive login and prompts through the shared SDK login runner
elkaix Aug 21, 2026
0b2dabf
feat(tui): unified shell-run cards, replay parity and print flushing
elkaix Aug 21, 2026
81aeb18
test(cli): cover region, login provider selection, shell-run and replay
elkaix Aug 21, 2026
c60a884
feat(inspect): workspace→session tree over grouped v2 listing
elkaix Aug 21, 2026
aa35295
test(vscode): adapt harness integration to v2 session rewiring
elkaix Aug 21, 2026
2883c32
feat(plugin): add Tencent CloudBase to the curated marketplace
elkaix Aug 21, 2026
1436478
feat(plugin): expand pythinker-datasource stocks/news/macro coverage
elkaix Aug 21, 2026
9913b04
chore: pin Node.js 24.x (24.15 – <25) across the workspace
elkaix Aug 21, 2026
8968c0f
chore(flake): pin nixpkgs nodejs_24 with <25 ceiling
elkaix Aug 21, 2026
5fd6a41
chore: bump package manifests for the port
elkaix Aug 21, 2026
299b357
chore(apps): version notes and disabled TUI full-screen in tests
elkaix Aug 21, 2026
96ec52a
docs: sync config, env-vars, keyboard and server-api guides
elkaix Aug 21, 2026
6fe85c8
feat(cli): refresh the bundled web UI and welcome asset
elkaix Aug 21, 2026
593ea12
style(web): apply oxlint auto-fixes to chat pane and helpers
elkaix Aug 21, 2026
cec3253
chore(core-v2): regenerate wire/state manifests for the feature seam
elkaix Aug 21, 2026
42d3cff
chore(changeset): refresh the port's pending changeset set
elkaix Aug 21, 2026
fa6c1a3
feat(cli): refresh the bundled web UI with the newest build
elkaix Aug 21, 2026
cfa4cf7
feat(web): uncommitted ProviderSetupForm component and its tests
elkaix Aug 21, 2026
192ae33
fix(web): keep completed subagents terminal on stale progress and reu…
elkaix Aug 21, 2026
e8a51e0
fix(web): restore ProviderSetupForm after AppProviderSetup removal
elkaix Aug 21, 2026
a7be162
chore(web): rebuild committed dist-web bundle
elkaix Aug 21, 2026
b78ad1b
fix(gateway): coalesce instance registry heartbeat writes
elkaix Aug 21, 2026
50e05e6
fix(gateway): deliver subagent lifecycle events outside transcript pr…
elkaix Aug 21, 2026
ba3dc4b
fix(agent-core-v2): emit rejected tool results with the declared reas…
elkaix Aug 21, 2026
2e112d7
test(agent-core): cover gateImageFormatParts
elkaix Aug 21, 2026
42a2c17
fix(brand): regenerate all pythinker icons from the unclipped vector …
elkaix Aug 21, 2026
b2d572d
merge: absorb main's vendor snapshot, resolving every conflict toward…
elkaix Aug 22, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
6 changes: 3 additions & 3 deletions .agents/skills/agent-core-dev/permission.md
Original file line numberDiff line numberDiff line change
Expand Up@@ -132,7 +132,7 @@ In `resolveExecution(input)`, before execution, declare accessed resources with

```ts
resolveExecution(args: WriteInput): ToolExecution {
const path = resolvePathAccessPath(args.path, { kaos, workspace, operation: 'write' });
const path = resolvePathAccessPath(args.path, { pyaos, workspace, operation: 'write' });
return {
accesses: ToolAccesses.writeFile(path), // declares: write this file
approvalRule: literalRulePattern(this.name, path),
Expand All@@ -155,7 +155,7 @@ Two complementary channels:
- **Enumerable resources** (write/read/edit/grep/glob) → use `accesses`; generic file dimensions cover them automatically.
- **Non-enumerable resources** (bash running arbitrary commands) → do not declare `accesses`; use the `matchesRule` DSL (e.g. `Bash(rm *)` globs by command string).

**kaos's role:** kaos is the execution-environment abstraction (fs/process/pathClass) used by the file dimension for path normalization and judgment — it is **not** the permission-dimension abstraction itself. Permission semantics live one layer above kaos, at "file access".
**pyaos's role:** pyaos is the execution-environment abstraction (fs/process/pathClass) used by the file dimension for path normalization and judgment — it is **not** the permission-dimension abstraction itself. Permission semantics live one layer above pyaos, at "file access".

**v2 evolution:** extend the `ToolResourceAccess` union so non-file resources can be declared structurally:

Expand DownExpand Up@@ -209,5 +209,5 @@ Incremental, not big-bang:
- Product reviews (plan/goal) are not permissions either: the owning domain intercepts its tool with a cold `event.waitUntil(factory)` and drives `IAgentToolApprovalService` itself; the gate only handles chain asks.
- The chain encodes dimensions, not tools: a new tool must not lengthen the chain.
- New specifics go through the data path (rules); only new risk behavior goes through the code path (a policy node).
- Tools only declare `accesses`; generic dimensions consume them. kaos is the execution environment, not the permission abstraction.
- Tools only declare `accesses`; generic dimensions consume them. pyaos is the execution environment, not the permission abstraction.
- Use `factory` (Agent-scope instantiation), not `instance`, for registered policies.
2 changes: 1 addition & 1 deletion .agents/skills/agent-core-dev/telemetry.md
Original file line numberDiff line numberDiff line change
Expand Up@@ -59,7 +59,7 @@ export interface ITelemetryAppender {
Built-in appenders:

- `ConsoleAppender` — `[telemetry] <event> <json>` to a log function (default `console.log`); options `prefix` / `pretty` / `log`.
- `CloudAppender` — batches events, enriches with common context (`app_name` / `version` / `platform` / …), and posts to `https://telemetry-logs.kimi.com/v1/event` through `CloudTransport` (Bearer auth, retry, on-disk fallback). Options: `homeDir` / `deviceId` / `sessionId?` / `appName` / `version` / `uiMode?` / `model?` / `getAccessToken?` / `endpoint?` / `flushThreshold?` / `flushIntervalMs?`.
- `CloudAppender` — batches events, enriches with common context (`app_name` / `version` / `platform` / …), and posts to `https://telemetry-logs.pythinker.com/v1/event` through `CloudTransport` (Bearer auth, retry, on-disk fallback). Options: `homeDir` / `deviceId` / `sessionId?` / `appName` / `version` / `uiMode?` / `model?` / `getAccessToken?` / `endpoint?` / `flushThreshold?` / `flushIntervalMs?`.

### Registering appenders (bootstrap)

Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/agent-core-dev/test.md
Original file line numberDiff line numberDiff line change
Expand Up@@ -160,7 +160,7 @@ export function registerLogServices(reg: ServiceRegistration): void {
ix = createServices(disposables, {
base: [registerLogServices, registerConfigServices, registerRecordsServices],
additionalServices: (reg) => {
reg.definePartialInstance(IAgentKaos, {}); // one-off collaborator
reg.definePartialInstance(IAgentPyaos, {}); // one-off collaborator
reg.define(IAgentRecords, spyRecords); // override a base default
reg.define(IXxxService, XxxService); // system under test
},
Expand Down
213 changes: 35 additions & 178 deletions .agents/skills/gen-changesets/SKILL.md

Large diffs are not rendered by default.

86 changes: 86 additions & 0 deletions .agents/skills/gitnexus/gitnexus-cli/SKILL.md
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
---
name: gitnexus-cli
description: "Use when the user needs to run GitNexus CLI commands like analyze/index a repo, check status, clean the index, generate a wiki, or list indexed repos. Examples: \"Index this repo\", \"Reanalyze the codebase\", \"Generate a wiki\""
---

# GitNexus CLI Commands

Commands below use `node .gitnexus/run.cjs <command>` — the project-local runner `gitnexus analyze` drops next to the index. It auto-selects an available runner at call time (global `gitnexus`, else `pnpm dlx`, else `npx`), so no package-manager assumption and no global install is required.

> **Not analyzed yet, or `node .gitnexus/run.cjs` reports `Cannot find module`** (the gitignored runner is absent — e.g. a fresh clone or `git clean`)? (Re)generate it with `npx gitnexus analyze` from the project root. On **npm 11.x**, if `npx` crashes during install (`node.target is null`), install once with `npm i -g gitnexus` (then `gitnexus analyze`) or use `pnpm --allow-build=@ladybugdb/core --allow-build=gitnexus --allow-build=tree-sitter dlx gitnexus@latest analyze`. See [#1939](https://github.com/abhigyanpatwari/GitNexus/issues/1939).

## Commands

### analyze — Build or refresh the index

```bash
node .gitnexus/run.cjs analyze
```

Run from the project root. This parses all source files, builds the knowledge graph, writes it to `.gitnexus/`, and generates AGENTS.md / AGENTS.md context files.

| Flag | Effect |
| -------------- | ---------------------------------------------------------------- |
| `--force` | Force full re-index even if up to date |
| `--embeddings` | Enable embedding generation for semantic search (off by default) |
| `--drop-embeddings` | Drop existing embeddings on rebuild. By default, an `analyze` without `--embeddings` preserves them. |
| `--pdg` | Build the program-dependence layers used by `explain` and `pdg_query` (taint, CDG, and REACHING_DEF). |

**When to run:** First time in a project, after major code changes, or when `gitnexus://repo/{name}/context` reports the index is stale. In Codex, a PostToolUse hook detects staleness after `git commit` and `git merge` and notifies the agent to run `analyze` — the hook does not run analyze itself, to avoid blocking the agent for up to 120s and risking KuzuDB corruption on timeout.

### status — Check index freshness

```bash
node .gitnexus/run.cjs status
```

Shows whether the current repo has a GitNexus index, when it was last updated, and symbol/relationship counts. Use this to check if re-indexing is needed.

### clean — Delete the index

```bash
node .gitnexus/run.cjs clean
```

Deletes the `.gitnexus/` directory and unregisters the repo from the global registry. Use before re-indexing if the index is corrupt or after removing GitNexus from a project.

| Flag | Effect |
| --------- | ------------------------------------------------- |
| `--force` | Skip confirmation prompt |
| `--all` | Clean all indexed repos, not just the current one |

### wiki — Generate documentation from the graph

```bash
node .gitnexus/run.cjs wiki
```

Generates repository documentation from the knowledge graph using an LLM. Requires an API key (saved to `~/.gitnexus/config.json` on first use).

| Flag | Effect |
| ------------------- | ----------------------------------------- |
| `--force` | Force full regeneration |
| `--model <model>` | LLM model (default: minimax/minimax-m2.5) |
| `--base-url <url>` | LLM API base URL |
| `--api-key <key>` | LLM API key |
| `--concurrency <n>` | Parallel LLM calls (default: 3) |
| `--gist` | Publish wiki as a public GitHub Gist |

### list — Show all indexed repos

```bash
node .gitnexus/run.cjs list
```

Lists all repositories registered in `~/.gitnexus/registry.json`. The MCP `list_repos` tool provides the same information.

## After Indexing

1. **Read `gitnexus://repo/{name}/context`** to verify the index loaded
2. Use the other GitNexus skills (`exploring`, `debugging`, `impact-analysis`, `refactoring`) for your task

## Troubleshooting

- **"Not inside a git repository"**: Run from a directory inside a git repo
- **Index is stale after re-analyzing**: Restart Codex to reload the MCP server
- **Embeddings slow**: Omit `--embeddings` (it's off by default) or set `OPENAI_API_KEY` for faster API-based embedding
101 changes: 101 additions & 0 deletions .agents/skills/gitnexus/gitnexus-debugging/SKILL.md
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
---
name: gitnexus-debugging
description: "Use when the user is debugging a bug, tracing an error, or asking why something fails. Examples: \"Why is X failing?\", \"Where does this error come from?\", \"Trace this bug\""
---

# Debugging with GitNexus

## When to Use

- "Why is this function failing?"
- "Trace where this error comes from"
- "Who calls this method?"
- "This endpoint returns 500"
- Investigating bugs, errors, or unexpected behavior

## Workflow

```
1. query({search_query: "<error or symptom>"}) → Find related execution flows
2. context({name: "<suspect>"}) → See callers/callees/processes
3. READ gitnexus://repo/{name}/process/{name} → Trace execution flow
4. cypher({statement: "MATCH path..."}) → Custom traces if needed
```

> If "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.

## Checklist

```
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] query for error text or related code
- [ ] Identify the suspect function from returned processes
- [ ] context to see callers and callees
- [ ] Trace execution flow via process resource if applicable
- [ ] cypher for custom call chain traces if needed
- [ ] Read source files to confirm root cause
```

## Debugging Patterns

| Symptom | GitNexus Approach |
| -------------------- | ---------------------------------------------------------- |
| Error message | `query` for error text → `context` on throw sites |
| Wrong return value | `context` on the function → trace callees for data flow |
| Intermittent failure | `context` → look for external calls, async deps |
| Performance issue | `context` → find symbols with many callers (hot paths) |
| Recent regression | `detect_changes` to see what your changes affect |
| "How does A reach B?" | `trace` between the two symbols — shortest call chain in one call |

## Tools

**query** — find code related to error:

```
query({search_query: "payment validation error"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError, PaymentException
```

**context** — full context for a suspect:

```
context({name: "validatePayment"})
→ Incoming calls: processCheckout, webhookHandler
→ Outgoing calls: verifyCard, fetchRates (external API!)
→ Processes: CheckoutFlow (step 3/7)
```

**cypher** — custom call chain traces:

```cypher
MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
RETURN [n IN nodes(path) | n.name] AS chain
```

**trace** — shortest call chain between two symbols ("how does A reach B?"), one call instead of chaining `context` hops:

```
trace({ from: "processCheckout", to: "fetchRates" })
→ status: ok, hopCount: 3
→ hops: processCheckout → validatePayment → verifyCard → fetchRates
→ edges: CALLS (1.0), CALLS (0.95), CALLS (1.0)
```

When no path exists, `trace` reports the furthest reachable node — exactly where the chain breaks (dynamic dispatch, reflection, or an external boundary).

## Example: "Payment endpoint returns 500 intermittently"

```
1. query({search_query: "payment error handling"})
→ Processes: CheckoutFlow, ErrorHandling
→ Symbols: validatePayment, handlePaymentError

2. context({name: "validatePayment"})
→ Outgoing calls: verifyCard, fetchRates (external API!)

3. READ gitnexus://repo/my-app/process/CheckoutFlow
→ Step 3: validatePayment → calls fetchRates (external)

4. Root cause: fetchRates calls external API without proper timeout
```
78 changes: 78 additions & 0 deletions .agents/skills/gitnexus/gitnexus-exploring/SKILL.md
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
---
name: gitnexus-exploring
description: "Use when the user asks how code works, wants to understand architecture, trace execution flows, or explore unfamiliar parts of the codebase. Examples: \"How does X work?\", \"What calls this function?\", \"Show me the auth flow\""
---

# Exploring Codebases with GitNexus

## When to Use

- "How does authentication work?"
- "What's the project structure?"
- "Show me the main components"
- "Where is the database logic?"
- Understanding code you haven't seen before

## Workflow

```
1. READ gitnexus://repos → Discover indexed repos
2. READ gitnexus://repo/{name}/context → Codebase overview, check staleness
3. query({search_query: "<what you want to understand>"}) → Find related execution flows
4. context({name: "<symbol>"}) → Deep dive on specific symbol
5. READ gitnexus://repo/{name}/process/{name} → Trace full execution flow
```

> If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.

## Checklist

```
- [ ] READ gitnexus://repo/{name}/context
- [ ] query for the concept you want to understand
- [ ] Review returned processes (execution flows)
- [ ] context on key symbols for callers/callees
- [ ] READ process resource for full execution traces
- [ ] Read source files for implementation details
```

## Resources

| Resource | What you get |
| --------------------------------------- | ------------------------------------------------------- |
| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |

## Tools

**query** — find execution flows related to a concept:

```
query({search_query: "payment processing"})
→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
→ Symbols grouped by flow with file locations
```

**context** — 360-degree view of a symbol:

```
context({name: "validateUser"})
→ Incoming calls: loginHandler, apiMiddleware
→ Outgoing calls: checkToken, getUserById
→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
```

## Example: "How does payment processing work?"

```
1. READ gitnexus://repo/my-app/context → 918 symbols, 45 processes
2. query({search_query: "payment processing"})
→ CheckoutFlow: processPayment → validateCard → chargeStripe
→ RefundFlow: initiateRefund → calculateRefund → processRefund
3. context({name: "processPayment"})
→ Incoming: checkoutHandler, webhookHandler
→ Outgoing: validateCard, chargeStripe, saveTransaction
4. Read src/payments/processor.ts for implementation details
```
Loading
Loading