> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recipe: Cross-Layer Debugging with 3 Knowledge Bases

> Index app, Terraform and GitOps as separate knowledge bases and let the AI connect the layers to diagnose a problem no single layer explains on its own.

An incident rarely lives in one layer. The pod won't go up — is it the **Argo manifest**? the **Terraform node group**? the **health check in code**? This recipe indexes all three layers as separate [knowledge bases](/features/knowledge-base) with [`@docs-flatten kind=code`](/features/knowledge-base) and lets the agent **cross** the bases to find the root cause.

## The Problem

The `checkout-api` `Rollout` is stuck in `Progressing` and never turns `Healthy`. Looking one layer at a time gets nowhere: the manifest looks right, Terraform applied without error, and the code compiles. The answer is **at the seam** — and it's spread across three repositories.

## Ingredients

* The application repository (service code).
* The infra Terraform module (cluster, node groups).
* The GitOps repository (Argo/Kubernetes manifests).
* ChatCLI with the builtin `@docs-flatten` tool (included).

<Note>
  No API key required: knowledge mode uses pure-Go BM25 by default. Embeddings ([Voyage/OpenAI/Bedrock](/features/quality/rag-hyde)) are an optional boost.
</Note>

***

## Step by Step

<Steps>
  <Step title="Index each layer as a base">
    `kind=code` slices each repo by structure — functions, Terraform resources, manifests — with symbol/resource titles, instead of one text blob:

    ```bash theme={"system"}
    @docs-flatten root=./checkout-api  kind=code format=jsonl output=app.jsonl
    @docs-flatten root=./infra-eks     kind=code format=jsonl output=infra.jsonl
    @docs-flatten root=./gitops-argo   kind=code format=jsonl output=argo.jsonl
    ```

    Noise (`vendor/`, `.terraform/`, lockfiles, binaries) is skipped automatically, and files above 1 MiB are ignored.
  </Step>

  <Step title="Create and attach the three bases">
    ```bash theme={"system"}
    /context create app   app.jsonl   --mode knowledge
    /context create infra infra.jsonl --mode knowledge
    /context create argo  argo.jsonl  --mode knowledge

    /context attach app && /context attach infra && /context attach argo
    ```

    Each attach costs only an **index card** (\~900 tokens, fixed) in the prompt — all three together stay cheap, even with large repos.
  </Step>

  <Step title="Ask across the layers">
    In `/agent` (or `/coder`), describe the symptom and let the AI connect. `@knowledge search` **fans out across the three bases**, tagging each passage by its source base:

    ```
    /agent the checkout-api Rollout stays in Progressing and never goes Healthy.
           connect the Argo manifest, the Terraform node group and the
           readiness/health check in the service code.
    ```

    Under the hood, the agent investigates iteratively:

    ```
    → @knowledge search "checkout-api Rollout readiness"      (base: argo)
    → @knowledge search "node group taints capacity"          (base: infra)
    → @knowledge search "health readiness endpoint port"      (base: app)
    → @knowledge get "argo/rollout-checkout.yaml"
    ```
  </Step>

  <Step title="Get the cross-layer diagnosis">
    With passages from all three layers in the same reasoning, the AI connects the dots — for example:

    > The `Rollout/checkout-api` (argo) sets `readinessProbe` on port **8080**, but the service (`app`, `server.go`) listens on **8081**; and `aws_eks_node_group.workers` (infra) has a `dedicated=checkout` taint the `Rollout` doesn't tolerate. **Two compounding factors**: the probe never passes and the pods don't even schedule onto the right nodes.

    The base is **read-only** — it gives understanding. To **apply the fix** and run the tests, use `/coder` on the live repo with `@read`/`@search`/`@coder`.
  </Step>
</Steps>

***

## Why it works

<CardGroup cols={2}>
  <Card title="Automatic fan-out" icon="arrows-split-up-and-left">
    `@knowledge search` queries **all** attached bases at once; each hit is tagged by its source base, so the model knows which layer it came from.
  </Card>

  <Card title="Structure-aware slicing" icon="cubes">
    Terraform resources, K8s manifests and functions become their own chunks with titles (`aws_eks_node_group.workers`, `Rollout/checkout-api`) — search lands on the right spot.
  </Card>

  <Card title="Fixed cost" icon="feather">
    A \~900-token index card per base, regardless of repo size. Three layers still fit in the prompt.
  </Card>

  <Card title="Keyless" icon="key">
    Pure-Go BM25 covers everything with no API key; identifiers (`getReadiness`, `checkout_api`) are found by their parts thanks to camelCase/snake splitting.
  </Card>
</CardGroup>

<Tip>
  You don't have to say "this is code" for each repo: the agent picks `kind=code` on its own from intent and a self-correcting hint. See [Knowledge Base](/features/knowledge-base).
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Knowledge Base" icon="book-open" href="/features/knowledge-base" />

  <Card title="Persistent Contexts" icon="box-archive" href="/features/persistent-context" />

  <Card title="Coder Mode" icon="code" href="/features/coder-plugin" />

  <Card title="K8s Monitoring" icon="dharmachakra" href="/cookbook/k8s-monitoring" />
</CardGroup>