setup-context

---
name: setup-context
description: Bootstrap a nao agent for a project — gather warehouse + scope + extra-context info in one round, look up the warehouse-specific config from nao docs, write nao_config.yaml, run nao init + nao sync, set up the LLM key, and generate the first RULES.md. Use when the user has just decided to use nao on a new project. Only for first-time setup; for editing rules, generating tests, or reviewing an existing context, use write-context-rules / create-context-tests / audit-context.
---

# setup-context

Take the user from `pip install nao-core` to a synced project with a starter `RULES.md`.

**Be brief.** One batch of questions, then act. Don't ping-pong.

**Scope ceiling: ≤100 tables.** Above that, sync gets slow and per-table context budget gets thin. 20 is a great target.

## Step 1 — Ask everything in one round

Send a single message asking for:

1. **Warehouse + auth** — type (BigQuery / Snowflake / Postgres / Redshift / DuckDB / Databricks / Athena / ClickHouse / Fabric / MSSQL / MySQL / Trino), and the auth credentials they have on hand. Tell them you'll fetch the exact field names from the nao docs once they pick a type.
2. **Scope** — which tables. Two valid shapes:
    - **Broad** — gold/marts across multiple domains (exec / cross-functional agents).
    - **Deep** — silver + gold for one domain (team-specific agents).
3. **Extra context** — dbt / ETL / BI repos, Notion, internal docs. Ask for **the SSH git URL** of each repo (e.g. `git@github.com:org/repo.git`) — sync clones them. No local paths.
4. **LLM** — provider and key. The model is selected in the nao UI, not in the config. Key comes later (Step 5).

## Step 2 — Look up warehouse fields, write `nao_config.yaml`, run `nao init`

1. **Fetch the warehouse-specific config** from [docs.getnao.io/nao-agent/context-builder/databases](https://docs.getnao.io/nao-agent/context-builder/databases). Each warehouse has its own required and optional fields (e.g. BigQuery needs `project_id` + `dataset_id` (optional); Snowflake needs `account_id` + `warehouse` + `schema_name` (optional); Postgres needs `host` + `port` + `database` + `schema_name` (optional). Ask the user for any required field you don't already have.

2. **Write `nao_config.yaml`** from the answers (skeleton in appendix below).

3. **Run `nao init --no-tty`** — it detects the pre-written yaml, skips all prompts, scaffolds the folder structure, and auto-installs missing dependencies. No interactive confirmation needed.

    Use this command (unsets leaked env vars from the parent agentic CLI — see Step 5):

    ```bash
    unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY && source ~/.zshrc 2>/dev/null; nao init --no-tty 2>&1
    ```

4. **Print a summary of `nao_config.yaml` to the user** before going further. Format example:

    ```
    nao_config.yaml summary
      • project: <name>
      • warehouse: BigQuery (project=<id>, dataset=<id>, auth=service-account)
      • scope: include=["analytics.fct_*", "analytics.dim_*"], exclude=[]
      • templates: [columns, preview, description]
      • repos: company-dbt (git@github.com:org/company-dbt.git)
      • llm: anthropic (key via ${{ env('ANTHROPIC_API_KEY') }})
    ```

    The model is configured in the nao UI, not in `nao_config.yaml` — don't include a model ID in the summary or the yaml.

    Ask the user to confirm before continuing. This is the last cheap chance to catch a wrong project, a misspelled dataset, or a missing repo.

### Database `templates` field

Per database in the yaml, set:

```yaml
templates: [columns, preview, description]
```

That's the set this skill ships. Other values are valid per-warehouse (`how_to_use`, `profiling`, `ai_summary`, and `indexes` for ClickHouse) — see the docs link above — but stick to `[columns, preview, description]` unless the user specifically asks otherwise.

**Don't use `accessors` — deprecated** (renamed to `templates`).

`nao init` creates: `nao_config.yaml`, empty `RULES.md`, `.naoignore`, and folders `databases/`, `repos/`, `docs/`, `semantics/`, `queries/`, `tests/`, `agent/{tools,mcps,skills}/`.

## Step 3 — `nao sync`

After the user confirms the summary in Step 2:

```bash
cd <project>   # where nao_config.yaml lives — every nao command runs from here
nao sync
```

Common failures: auth (fix yaml), tables not found (check schema casing), permission denied (grant read access), repo missing (fix `repos:` block, confirm SSH key). Don't move on until sync is clean.

## Step 4 — Generate `RULES.md` (no confirmation)

Hand off directly to `write-context-rules`. Don't ask.

## Step 5 — Wire up the LLM key

The key lives in `nao_config.yaml`. Two safe options:

- **Preferred:** env-var ref. Write `api_key: ${{ env('ANTHROPIC_API_KEY') }}` on the provider entry; tell the user to export the key in their shell.
- **If they insist on a literal:** tell them to edit the yaml themselves and add it to `.gitignore`. **Never** ask them to paste a key into chat.

Then `nao debug` to confirm.

### Known issue — `AI_APICallError: Not Found`

If `nao chat` / `nao debug` / `nao test` fails with that error and the URL is `https://api.anthropic.com/messages` (no `/v1/`), the parent agentic CLI (Claude Code, Cursor, Codex) is leaking `ANTHROPIC_BASE_URL` into the child env. Fix:

```bash
unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY && source ~/.zshrc 2>/dev/null; nao chat 2>&1
```

Regular human terminals aren't affected.

## Step 6 — Recommend next steps

1. Smoke test: `nao chat`, ask 3-5 real questions.
2. Review `RULES.md` for wrong inferences.
3. Pick a next skill: `write-context-rules` (refine), `create-context-tests` (benchmark), `audit-context` (anytime), `add-semantic-layer` (only after tests reveal metric-reliability gaps).

## Guardrails

- **`cd` into the project directory before any `nao` command.**
- **Cap at ~100 tables.**
- **One batch of questions.** Look up warehouse-specific fields from the docs, don't keep pinging the user.
- **Run `nao init --no-tty`** with the yaml pre-written — never run `nao init` without the flag.
- **Use `templates: [columns, preview, description]`.** Don't use `accessors`.
- **Repos: SSH git URLs only.** No local paths in the `repos:` block.
- **Print the `nao_config.yaml` summary** and get user confirmation before `nao sync`.
- **Never have the user paste their LLM key into chat.**
- **Don't ask before invoking `write-context-rules`** — just hand off.

## Appendix — `nao_config.yaml` skeleton (BigQuery example)

Use this shape and adapt the `databases:` block per warehouse — see [docs.getnao.io/nao-agent/context-builder/databases](https://docs.getnao.io/nao-agent/context-builder/databases) for the exact required/optional fields for Snowflake, Postgres, Redshift, Databricks, Athena, ClickHouse, Fabric, MSSQL, MySQL, Trino, MotherDuck.

```yaml
project_name: <project>

databases:
    - type: bigquery
      name: <connection-name>
      project_id: <gcp-project-id>
      dataset_id: <dataset>
      credentials_path: /path/to/service-account.json # or `sso: true`
      include: ['<dataset_pattern>.<table_pattern>'] # e.g. "analytics.fct_*" - use '*' as multiple patterns
      exclude: ['<pattern>']
      templates: [columns, preview, description]

llm:
    providers:
        - provider: anthropic # openai | bedrock | gemini | mistral | openrouter | ollama | vertex
          api_key: ${{ env('ANTHROPIC_API_KEY') }}
          models: # optional, defaults to the provider's built-in models
              - id: claude-sonnet-4-5
                default: true

repos:
    - name: <repo-name>
      url: git@github.com:<org>/<repo>.git # SSH only
```