setup-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] • 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] ``` Valid values are `columns`, `preview`, `profiling`, `query_history`, and `ai_summary`; the default is `[columns, preview]`. `profiling` and `query_history` are opt-in, and `query_history` requires BigQuery, Snowflake, Postgres, Redshift, Databricks, or a custom `query_history_sql`. **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]`.** 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] 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 ```