agami-connect
End-to-end database connection for agami: sets up credentials on first run (DB-type picker → writes <artifacts_dir>/local/credentials.example for the user to fill in), then introspects the live DB directly into the agami semantic model (subject areas, tables, columns, relationshi
Install
npx skills add https://github.com/AgamiAI/agami-core/tree/main/plugins/agami/skills/agami-connect
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agamiai-agami-core@llmmart
git clone https://github.com/AgamiAI/agami-core.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agamiai/agami-core collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
agami connect
Before suggesting any slash command in chat, read shared/invocation-conventions.md. Agami slash commands: /agami-connect, /agami-query, /agami-model, /agami-save-correction, /agami-reconcile. (/agami-model is also the trust-review surface — its Review tab absorbed the former /agami-review.) Never write the un-prefixed forms (/init, /connect, etc.) or colon forms (/agami:connect) — those don't exist. For chat replies, prefer natural language ("say 'reload the schema'", "say 'introspect my database'") — the when_to_use matcher routes correctly without an explicit slash command.
You are setting up the agami semantic model for the user's database. Goal: by the end there is a validated semantic model at <artifacts_dir>/<profile>/ (datasource.yaml + subject_areas/<area>/… + datasources/<connection>/storage.yaml), a seeded examples library at <artifacts_dir>/<profile>/prompt_examples/<area>/examples.yaml, an datasource.md the user can edit, and the user has seen one demo query execute end-to-end.
The structural model is built by a deterministic engine, not hand-authored. sm introspect (run as Phase 1.7 shows) introspects the live DB across all supported dialects — PostgreSQL (incl. Supabase / Redshift), MySQL/MariaDB, Snowflake, BigQuery, SQL Server, Oracle, Databricks, Trino/Presto, DuckDB, SQLite — into the model: storage connection, proposed subject areas, tables, columns + types, primary-key grain, foreign-key relationships with join cardinality, column_groups on wide tables, and sensitive flags on PII. When the catalog (information_schema / PRAGMA / data-dictionary) is reachable it runs in catalog mode; when a locked-down role denies the catalog it falls back per-capability to probe mode (describe via a zero-row header, infer types from a value sample, grain from uniqueness probes, FKs from name+overlap) and everything inferred lands unreviewed for sign-off. Your job is the layer the engine can't do: enrichment (prose descriptions, entities, metrics, caveats) and curation (subject-area boundaries, trust review).
If an sm call exits 12, agami's library is older than the plugin: run bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install (the person approves it), then repeat the call. It is not "no model" (exit 3): never send the person to agami-connect for it.
For the model format: semantic_model/__init__.py (layout) and the Pydantic models in packages/agami-core/src/semantic_model/models.py.
For credentials: shared/credentials-format.md.
For connection method + local execution: shared/connection-reference.md.
For DB error classification: shared/db_error_classifier.md.
For every decision card and result table: shared/question-cards.md.
Conversation style
- Combine acknowledge + next question — don't waste turns on "Got it!"
- Use AskUserQuestion for every Yes/No/Skip — never inline-bullet options. Where AskUserQuestion is unavailable, ask the same as a short numbered list (
shared/question-cards.mdrule 7). Use(Recommended)only when there's a genuine recommendation. For fact-of-environment questions ("which database type?", "which schemas?"), don't mark any option Recommended — the user picks what they have. - Every multiSelect needs an explicit "none / continue" option —
AskUserQuestioncannot be submitted with zero boxes checked, so any multiSelect where "pick nothing" is a valid answer MUST offer a selectable "Nothing — continue" (or "Keep everything") option. Never phrase the prompt as "leave all unchecked" — that's unsubmittable and traps the user. - Ask the business, decide the plumbing (
shared/question-cards.mdrule 9): a card asks only what the data means to the business, in plain words with an example. Batches,--append,--no-safety, mapping thresholds and the like are yours to decide, conservatively, and to report in one line. A card never names a file or table without saying what it is. Before signing answers that came back the same down a whole column of a page or sheet, confirm in one line (rule 10). - Keep the user oriented — print one-line progress markers between phases (
✓ Introspected 12 tables,✓ Validator passed,✓ Generated 10 examples). - Plain voice — state what happened, never how impressive it is. Progress markers, todo labels, and narration describe the action and the result; they do NOT editorialize. Banned: "wow moment", "magic", "watch this", "the exciting part", "you'll love this", exclamation hype. The reader is a data professional — a query running correctly speaks for itself. Say "Running the first query", not "Now the wow moment".
Progress tracking — the onboarding steps, shown the whole way
This is a multi-phase skill, with cards in between. The very first action on every invocation is to show the onboarding steps as a task list, and to keep it current, so the person always knows where they are and what's left. Once the database's folder exists, the list is drawn from sm steps, which prints every step with its status and its numbers read from disk; how and when to run it, and where the list goes, is in shared/task-list.md. Each phase below marks its own step when it starts and ends.
The same steps every run, in the person's words (no "introspect", "enrich" or "NL→SQL"):
1. Connect your database
2. Tell agami about your data
3. Pick the tables
4. Read the tables and joins
5. Describe columns and add metrics
6. Answer what the data can't settle
7. Sign off definitions and hide personal data
8. Write and check example questions
9. Check your reports
10. Summary and first question
Leave out a step that won't run (6 when "Ask me as you go" wasn't picked in 1.5; 9 when no reports were shared in 1.5; 3 with a model spec workbook, which names the tables): mark it skipped, and sm steps leaves it out of the list; never add your own working steps to this list. When a step finishes, add its numbers to its label, so the list reads as a running summary: "Read the tables and joins — 21 tables, 19 joins", "Describe columns and add metrics — 93% described, 7 metrics", "Sign off definitions and hide personal data — 5 of 7 signed". The label with its numbers is the step's line in the list that sm steps prints, copied as printed without its mark, never typed by hand and never an estimate; a step with nothing to count keeps its plain label. While a long step runs, its label carries the live count too ("Read the tables and joins — 30 of 52 tables"), from the same line, which sm progress --wait prints in its own list on every pass, so the list shows movement during a wait and not only at the end. Mark each step in progress when it starts and done the moment it ends, exactly one in progress at a time, and keep it in progress while a card for that step is waiting, so the list shows where the person is while they decide.
Don't seed it again if the list already holds these steps (the skill is resuming after a hand-off, a password page or a file wait): run sm steps "<root>" first and show what it prints (shared/task-list.md, resuming). When $ARGUMENTS == reintrospect, the list restarts at the first step this run marks started (step 2, when Phase 1 begins): sm steps reopens that step and every step after it, and keeps the steps before it done.
Phase −1: Plan-mode check
Run the detection + ask logic from shared/plan-mode-check.md. agami-connect needs Bash (introspection) and Write (model files) — both blocked in plan mode.
If plan mode is active and the user stays in plan mode (or the skill is invoked under plan mode with no prompt): refuse with the one-liner below and end the turn. DO NOT write a plan file. DO NOT call ExitPlanMode.
I can't introspect in plan mode — switch to Auto or Edit Automatically mode (Shift+Tab to cycle) and re-invoke me. Introspection, enrichment, and the demo query all need write access to
<artifacts_dir>/<profile>/.
If plan mode is not active, skip silently.
Phase 0: Preflight
HARD RULES — read before doing anything
Non-negotiable. They override every other instruction here when they conflict.
- Connect ONLY to the host/port/database/user/password in
<artifacts_dir>/local/credentials. That file is the sole credential source — there is no env-var bypass. Never connect to anything else. Never probelocalhostunless the credentials say so. Never substitute defaults for missing fields. - Never ask for a password in chat. Nor any other secret: a password, an access token, a key (or a key file's contents), or a DSN that contains a password. Not even temporarily, and never echo one back. The non-secret fields (host, port, database, user, account, warehouse, a file path) ARE asked in chat, on the connection cards in 0a.4c: they are not secret, they already appear in the credentials file in plain text, and a card is faster than editing a file. The secret goes only through a path that keeps it out of the chat, the transcript, and your context: on macOS and Windows the one-time local page of 0a.4k (it goes straight to the OS credential store), on Linux (and for a Databricks token anywhere) the
credentials.examplefile of 0a.4 that the person fills in themselves. If the person types a secret into the chat anyway, don't use or repeat it: say it should not be shared in chat, suggest they change it, and carry on with the page or the file. - Never scan or guess. No
pgrep,ps,lsof,find /,ls /Applications, no port-listener scans, no testing connections to common hostnames. The only acceptable Bash probes here arewhich <tool>andbash "${CLAUDE_PLUGIN_ROOT}/scripts/py" -c 'import <module>'. - If credentials are missing for the active profile, run Phase 0a. It ends connected (the password page, 0a.4k) or with a card that waits for the filled-in file (0a.9). A person who closes the chat instead can come back later with any data question —
agami-queryauto-invokes us and 0a.10 picks the file up. - NEVER put a credential on a Bash command line — no
export PGPASSWORD=…, nopsql -W <pw>, no heredoc that interpolates a secret. Hosts render Bash calls in chat; anything on the line leaks. Runtime queries use the auth files fromscripts/setup_pgauth.py(psql/mysql) orpython -m execute_sql(every driver, reads<artifacts_dir>/local/credentialsitself). Seeshared/connection-reference.md → HARD RULES. - Run each agami command as its own Bash call:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" <verb> …with every path written out in full. Never put a variable assignment, a pipe,;,&&, a redirect or a filter on the line, and never run two agami commands in one call. A line written any other way always stops to ask the person for permission; written this way agami's own hook approves the read-only commands and scratch files without a prompt, and every other command asks as usual. Read the whole output: the commands print only what you need. Where a command starts withAGAMI_SCRATCH_ONLY=1(andAGAMI_SQL_MAX_ROWS=200000before it ondiscoverandintrospect), copy that prefix exactly: it holds every file the call names to agami's scratch folder.<root>is the database's model folder,<artifacts_dir>/<profile>, written out in full; the artifacts folder is preflight step 1'sartifacts_dir, never read from the pointer file; scratch files go only in<artifacts_dir>/local/tmp/, namedagami-…, never/tmp, and are written with the Write tool (shared/invocation-conventions.md). The person's own words (a company name, a description, a question) go tosmthrough a file the same way (--name-file,--description-file,--question-file), never on the command line. - Do what the engine says. When an agami command's output has
say, post it as written; when it hasthen, do that next.
If you reach for a command that doesn't fit, stop and re-read this section.
Preflight steps
Sample-path short-circuit (check FIRST, before resolving any profile). If the user explicitly asked for the sample —
$ARGUMENTSissample, or they said "try the sample" / "I don't have a database" / "use the sample (or example) data" / "demo data" — then bind$PROFILE_NAME = agami-example,$DB_TYPE = sample, and go straight to Phase 0s. Do this regardless of any existingactive_profileor onboarded profiles — the sample is a deliberate, explicit choice and must not be intercepted by another profile's credential/existing-model checks. (A returning person also gets "Try the sample data" on the start card in step 1a; this short-circuit covers the request that already says so.) Ifagami-exampleis already set up, Phase 0s sends them to the demo. Only fall through to step 1 when there's no sample signal.Resolve the environment —
bash "${CLAUDE_PLUGIN_ROOT}/scripts/py" connect_resolve.py [--db-type <t>] [--profile <p>]prints{data, anomalies}(self-describing JSON): profile, artifacts_dir, the[<profile>]credentials section + chmod, the cached config,interpreter.python3(the one Pythonsm,pyand the install all use — use it everywhere; what it lacks,core_readyandhas_driversay), nativetools, and anextdecision. Branch ondata.next:ready→ the start card for a returning person (step 1a); a reload or re-introspect request skips the card and goes straight to Phase 1 withreintrospect;build→ the database's credentials are saved but it has no model yet (the build never ran or never finished): there is nothing to ask yet, so show no start card and never offer "Ask a question"; say in one line "<database>is connected but not built yet, so I'll build it now." and go straight to Phase 1 (a fresh build, notreintrospect), unless the request already names another action (the sample, or connecting a different database);promote→ run 0a.10 to promote the filled template, then continue;bootstrap→ the first-run start card (step 1a), then Phase 0a. On a first-time bootstrapdata.profileisnull(profile_source: "default") — there's no profile yet, so narrate it without a name: "No credentials yet — first-time setup." (Never say "profilemain" — the user names their profile in 0a.3.) Only whendata.profileis non-null (abootstrapfor an explicitly-named/env profile) may you name it. Surfaceanomalies.agami_python_lackscomes first and stops the run: the$AGAMI_PYTHONthe person set lacks the model deps or the driver, and agami uses that Python and no other, so say itsdetail(the path, what it lacks and the exact install line) before anything else, and go no further until they have run it or changedAGAMI_PYTHON; then resolve again. The others (e.g.credentials_world_readable→ offerchmod 600;library_older_than_plugin→ offerbash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install, or theAGAMI_PYTHONfix it names;agami_python_cannot_be_brought_current→ the$AGAMI_PYTHONthe user set has no pip and an old or missing agami-core, so say so;env_profile_has_no_model→AGAMI_PROFILEnames a database with no model while others have one: say itsdetailin one line before the start card, and offer the databases it lists rather than a new connection under that name, unless the person asked to connect one).interpreter.chosen_becausesays why that Python was picked, and a candidate passed over carries areason; never substitute amissing_fieldsvalue — surface "missing field X for profile Y" and stop. 1a. The start card (conventions:shared/question-cards.md). One AskUserQuestion, one question, headerStart. Skip it when the request already names the action:$ARGUMENTSisreintrospectorprofile NAME, the person asked to reload or re-introspect, to add a new database (go to Phase 0a), oragami-queryinvoked this skill because a model is missing (go to Phase 0a).First run (
data.nextisbootstrap, nothing connected yet). Question: "How do you want to start?" No option is marked Recommended: whether there is a database to connect is a fact about the person's setup.label description then Connect a databaseYour own database; the password never goes through the chat Phase 0a Try the sample dataA small demo store, no connection needed Phase 0s Connected but not built (
data.nextisbuild). No start card: go straight into the build (step 1). A database with no model has nothing to ask, soAsk a questionis never offered for it.Returning (
data.nextisready: a database is already connected and built). Question: "What would you like to do?"label description then Ask a question (Recommended)Ask <active database>somethingHand to agami-query. A question typed in "Other" goes straight there. Picked with no text: offer a card of up to 4 questions taken from that database's seed examples ( prompt_examples/), with "Other" for their own.Reload the schemaPick up new or changed tables, keeping descriptions, metrics and sign-offs Phase 1 as reintrospect(the 1.1 Re-introspect path; 2e previews, then writes).Connect another databaseAdd a different database alongside this one 1.1a first (same company or a different one), then Phase 0a (the new database gets its own name in 0a.3). Try the sample dataA small demo store, no connection needed Phase 0s An empty database gets no recommendation to ask it. When every table in the active database's
sm model-treehasrowsof 0, the first option isAsk a questionwithout "(Recommended)", its description says ", andConnect another databaseis marked (Recommended) instead.Route "Other" text by what it asks for. An action goes to that action: re-introspect, reload or refresh the schema →
Reload the schema; add a schema that lives in the same database →Reload the schemawith the schema selection in 1.3 widened to the old and new schemas (see the note under 1.1: same database, another schema is a re-introspect, never a new database); review or sign off the model, edit descriptions, exclude tables → agami-model; add or connect a different database →Connect another database; answer the open questions, or what the data can't settle → 2g on the active database. Only a question goes to agami-query. When the text could be either (a schema name alone, say), ask which with a card rather than guess.This card replaces the 1.1 menu for a returning person; don't ask 1.1 again after it.
Say "database", never "profile", in the card and around it.
Update-check (best-effort). Run the probe from
shared/version-check.md; surface a one-liner if a newer version exists. Never block on network failure.If
$ARGUMENTSisreintrospect: re-introspect from scratch, but preserve hand-edits (descriptions, entities, metrics, caveats, trust sign-offs). The engine writes the structural skeleton; merge it over the existing enrichment rather than discarding it (see Phase 2's reintrospect note).
Phase 0a: First-time credential bootstrap
Runs when preflight step 1 returns next: bootstrap (no credentials for the profile) and the person picked "Connect a database", or when they picked "Connect another database". If <artifacts_dir>/local/credentials already has the [<profile>] section for the database being connected, skip Phase 0a entirely.
Two paths, chosen by the operating system, which the session's environment already names (the platform: darwin is macOS, win32 is Windows, linux is Linux); don't run a command to find it:
- macOS and Windows: the password page. 0a.0 → 0a.5b → 0a.6 → 0a.1 → 0a.2 → 0a.4c (connection fields card) → 0a.3 (the name, offering the database's own name) → 0a.5 → 0a.7 → 0a.8 → 0a.4k (the password page) → Phase 1. No file to edit and nothing to paste. The page needs the interpreter, agami-core (with
keyring) and the artifacts folder in place, which is why 0a.5–0a.8 run before it. - Linux and anything else, and Databricks on every system (its secret is a
token, and the page stores apassword): the file. 0a.0 → 0a.5b → 0a.6 → 0a.1 → 0a.2 → 0a.3 → 0a.4 (credentials.example) → 0a.5 → 0a.7 → 0a.8 → 0a.9 (a card waits for the filled-in file) → 0a.10 → Phase 1.
0a.0 — Before you start: what to have ready, then the organisation and the source system
First, before the database-type card, say in one short message what helps to have to hand, so nobody is asked mid-build for something they could have fetched up front. None of it is required:
Before we connect, it helps to have these to hand (none is required):
- What your organisation does, in a sentence or two.
- What system the data comes from (a product such as ServiceNow or Salesforce, or your own application), and anything about the database: when your fiscal year starts, what currency amounts are in, whether the warehouse already controls who sees personal data.
- Definitions of the tables and columns: a data dictionary, a spec workbook, a dbt or LookML project.
- Definitions of your metrics and business terms.
- The questions people ask. They become checked examples, and how many of them agami answers correctly is how you can tell the model is right.
Then ask 1 and 2 as their own first questions, on one card (two questions; leave the Company one out when it was already authored, as 1.4 A says):
- The Company question is 1.4 A's
Companycard, asked here instead of after the connection. 1.4 A says what to write, and it is written once the folder exists (below). - The Source question, header
Source: "What system does this data come from? Add anything about the database too, e.g. "ServiceNow; fiscal year starts in July; amounts in USD". Type it in Other." Options: Our own application (built in-house, no product dictionary) and Not sure (agami reads the database and works it out). No option is marked Recommended: it is a fact about their setup.
Both answers are hints, never copied verbatim into the model. They steer the descriptions written in Phase 2 (a domain prior, like the narrative) and switch on product-specific help; no description, glossary entry or rule is the person's sentence pasted in.
Hold the answers; write nothing yet. At this point there is no artifacts folder (0a.6 picks it) and no interpreter (0a.5 finds it), so sm can't run. Bind them now and write each where the list below says: the company and the personal-data setting right after 0a.8, when the folder and the interpreter exist; the fiscal year after 1.7, when datasource.yaml exists. Bind the Source answer:
- A named product →
$SOURCE_SYSTEM. When agami has a metadata preset for it (ServiceNow:servicenow), 2a.0 passes--preset servicenowtosm enrich-metadata, which reads the product's dictionary and choice tables straight from the database without modelling them. So never add the preset's source tables (sys_dictionary,sys_choice, or a warehouse copy under another name) to 1.6's kept set: 2a.0'senrich-metadata --preset <name>reads them directly, and kept they are modelled as ordinary tables. And 1.5's published-product-schema path is already on. Say it in one line: "ServiceNow: I'll read its own data dictionary for the column meanings." - A fiscal year start, stated plainly →
$FISCAL_START_MONTH(1 to 12). After 1.7 write it withbash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" set-fiscal-year "<root>" --month <month>, the same write 1.4 D makes, and skip 1.4 D's card. Anything vaguer ("our year is odd") is not a month: 1.4 D asks it. - A currency, stated plainly →
$CURRENCY_HINT, a hint only: nothing is written now. 2d offers it as the currency for the money columnssm suggest-unitsfinds (sm set-units --currency <ISO code>), and the person still agrees to that plan there. - The warehouse already controls who sees personal data (column- or row-level security, "our warehouse handles PII") → after 0a.8, before the build:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" set-personal-data "<artifacts_dir>" enforced_by_warehouse. It is a build-only setting, kept in<artifacts_dir>/local/.configand never deployed. The build then flags nothing personal and Phase 4 skips the personal-data question. Say it in one line.set-personal-data "<artifacts_dir>" flagged_by_agamiundoes it (a reload flags again). - Our own application / Not sure → nothing is written; the build works from the database.
Items 3 to 5 are handed over on 1.5's context card (its Definitions or a semantic layer and Questions people ask options); the questions people ask go to <artifacts_dir>/local/tmp/agami-asked-questions.txt and become checked examples in Phase 5, as they do today. Don't ask for them here.
When Phase 0a is skipped (the credentials already exist), ask this step at the start of 1.4 instead, on a first onboard of that database. Not on reintrospect.
0a.1 — Set up <artifacts_dir>/local/
<artifacts_dir> is settled by now: 0a.6 chose it on a first run and saved it with sm choose-folder, and otherwise it is the resolve step's data.artifacts_dir. One call creates the folder, its private local/ (0700) and scratch folder, and makes <artifacts_dir>/.gitignore ignore local/ (no Write, Read or mkdir of your own):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" init-local "<artifacts_dir>"
It works only on agami's own artifacts folder: an error naming another folder means 0a.6's choose-folder call hasn't run. It never installs anything: exit code 12 means agami's library isn't installed yet, so ask 0a.5b's card and run sm install first, then this call again.
0a.2 — Ask the database type
AskUserQuestion, one question, header DB type, no (Recommended) — fact-of-environment. The sample data is on the start card (1a), not here.
Name the Other-only engines in the QUESTION PROMPT so they're visibly supported — the auto-provided "Other" field can't carry its own description/examples, so the examples must live in the prompt. End the prompt with a line like:
Something else — BigQuery, SQL Server, Oracle, Databricks, Trino/Presto, DuckDB, or SQLite? Choose Other and type it (a name or a file path).
| label | description |
|---|---|
PostgreSQL |
Postgres + compatible: Supabase, Neon, RDS, Aurora, Cloud SQL, Timescale, and Amazon Redshift (port 5439, SSL by default). |
MySQL |
MySQL, MariaDB, RDS MySQL, PlanetScale. |
Snowflake |
Snowflake. Account identifier instead of host. |
Other (Other field) |
BigQuery, SQL Server, Oracle, Databricks, Trino/Presto, DuckDB, SQLite. |
Bind $DB_TYPE ∈ postgres | mysql | snowflake | bigquery | sqlserver | oracle | databricks | trino | duckdb | sqlite | dsn.
Routing:
- "sample" typed in Other (or "I don't have a database") → Phase 0s, as on the start card.
PostgreSQL→postgres; if the user later enters port5439or a*.redshift.*.amazonaws.comhost, transparently re-bind toredshift. A*.pooler.supabase.comhost stayspostgres(Supabase is hosted Postgres).MySQL/Snowflake→ pass-through.BigQuerylives under Other now (or the user types it) →bigquery.Other→ parse the free-form input: a DSN scheme → derivedb_type(if it carries a password, follow HARD RULE 2: don't use or repeat it, ask the fields on 0a.4c instead);.db/.sqlite/.duckdbsuffix or absolute file path → SQLite or DuckDB; a named DB (bigquery,sqlserver/mssql,oracle,databricks,trino/presto,duckdb) → that dialect. Only refuse with "not supported yet" for engines outside the supported set above (e.g. MongoDB, Cassandra, ClickHouse).
0a.3 — Name the database (the person's choice)
Ask the user to name this connection — don't pick for them. The name is how they'll switch databases later (AGAMI_PROFILE=<name>) and it names the model folder (<artifacts_dir>/<name>/), so a name that means something to them — their database, product, team, or environment — beats a generic default.
On the password-page path this card comes after the connection fields (0a.4c), because the fields card asks for the database's own name and a separate "what should I call this database?" before it reads as the same question twice. Here the name is for the connection, and the database name the person just gave is the natural answer. AskUserQuestion, header Name:
"What should agami call this connection? It's how you'll pick it when you connect more than one. Type your own in Other."
Options: <database> (Recommended), the database name from 0a.4c made valid (lowercased, any other character turned into -, trimmed to 32), and <database>-<where>, with <where> = local for localhost/127.0.0.1 or the first label of the host otherwise (<database>-<account> on Snowflake, <project> alone on BigQuery, the file's stem for SQLite and DuckDB). Leave out an option that would equal the other or fail the rules below.
On the file path (no fields card), ask it here, before the file: "What should agami call this database? It's how you'll pick it when you connect more than one, so your database or product name works well. Type it in Other." with prod, staging and analytics as examples. Don't present a main default that nudges them past the choice.
Bind $PROFILE_NAME to their answer (the Other text, or a picked option). Validate: lowercase letters/digits/dashes/underscores, 1–32 chars; and not already a [section] in <artifacts_dir>/local/credentials (a profile name is a unique key — reusing one would clash). If it fails either rule, show the reason and re-ask. (The 0a.10 promote helper enforces the uniqueness backstop too — it returns COLLISION rather than overwrite — but catch it here so the user isn't surprised later. On the password-page path the helper checks again, and also refuses a name the OS store already holds a password under.) Say "database", not "profile", to the person.
0a.4c — The connection fields as one card (macOS and Windows)
Only on the password-page path (see the top of Phase 0a). Linux, and Databricks on any system, use the file in 0a.4 instead.
One AskUserQuestion, header per question, one question per non-secret field (at most 4). The password is never on this card: it goes on the page in 0a.4k. Every question takes the real value in "Other"; the options are the obvious defaults and common values, so the person presses one when it fits and types otherwise. No option is marked Recommended (these are facts about their setup). Put a line in the first question's prompt: "Type yours in Other when the options don't fit, for example your-cluster.example.com (never a password or a URL that holds one: the password goes on a separate page)."
$DB_TYPE |
questions (header: options) | spec fields keys |
auth |
|---|---|---|---|
| postgres / redshift | Host: localhost (this computer), 127.0.0.1 · Port: 5432 (PostgreSQL default), 5439 (Amazon Redshift), 6543 (Supabase pooler) · Database: postgres (the default database), analytics · User: readonly (a read-only user, the safest), postgres |
host, port, database, user |
password |
| mysql | Host: as above · Port: 3306 (MySQL default), 3307 · Database: analytics, app · User: readonly, root |
same | password |
| sqlserver | Host: as above · Port: 1433 (default), 1434 · Database: master, analytics · User: readonly, sa |
same | password |
| oracle | Host: as above · Port: 1521 (default), 1522 · Service: ORCLPDB1, XEPDB1 · User: readonly, system |
host, port, service_name, user |
password |
| snowflake | Account: acme-xy12345 (org-account form), xy12345.us-east-1 (locator form) · User: readonly, analyst · Warehouse: COMPUTE_WH (Snowflake's default), ANALYTICS_WH · Sign-in: Password (typed on a one-time page), Browser sign-in (SSO) (your company's sign-in, no password) |
account, user, warehouse (+ authenticator = externalbrowser for SSO) |
password, or sso for browser sign-in |
| trino | Host: as above · Port: 8080 (HTTP default), 443 (HTTPS) · User: readonly, admin · Catalog: hive, iceberg; then a second card, Password: No password, Password (HTTPS) |
host, port, user, catalog |
sso for no password, else password |
| bigquery | Project: acme-analytics, acme-prod · Sign-in: Google sign-in on this computer (gcloud application-default login), A service-account key file (its path in Other; the path, never the file's contents) |
project (+ service_account_path) |
sso |
| sqlite / duckdb | File: the absolute path in Other; options ~/data/app.db, ~/data/app.duckdb (examples) |
path |
sso |
Snowflake's database, schema and role, and Postgres' sslmode, are optional: ask them on a second card only when the person mentions them or the connection fails without them.
Read the answers into the spec's fields, as strings. Expand ~ to an absolute path. When an answer can't be used, say why in one line and ask that question again (an empty answer; a port that isn't a number; an example value such as acme-xy12345 or one containing example that is plainly not theirs; a value with %, or starting with # or ;, which the credentials file can't hold). A host that is a full URL with a password in it: don't use or repeat it (HARD RULE 2), and ask for the host alone.
Then run 0a.5 → 0a.8 (interpreter, agami-core, the artifacts folder, .config), and go to 0a.4k.
0a.4k — the password page (macOS and Windows)
The password goes from the person's browser straight into the OS credential store (Keychain on macOS, Credential Manager on Windows). It is never in the chat, on a command line, in a file, or in your context: you never see it, so never ask for it, and if it is typed into the chat anyway, follow HARD RULE 2.
1. Write the spec with the Write tool to <artifacts_dir>/local/tmp/agami-connect-spec.json (non-secret fields only; there is no password key):
{"profile": "<$PROFILE_NAME>", "db_type": "<$DB_TYPE>",
"fields": {"host": "<host>", "port": "<port>", "database": "<database>", "user": "<user>"}}
For a connection with no secret to type (Snowflake browser sign-in, BigQuery, Trino with no password, SQLite, DuckDB) add "auth": "sso". The sso path has no link and no page: the helper writes the section, tests the connection, and prints only its final line, so skip step 3 and read that line in step 4. Its wait is longer than the password path's (step 2).
2. Start the helper in the background. Call Bash with run_in_background: true:
bash "${CLAUDE_PLUGIN_ROOT}/scripts/py" connect_helper.py --spec "<artifacts_dir>/local/tmp/agami-connect-spec.json"
Stdout is JSON lines and nothing else. Wait for the helper's first line with the Monitor tool: the Bash result names the task and its output file, so use the Monitor tool to watch the helper's output until its first line, or the task's exit (an until-loop on that output file that stops on the first JSON line, or when the task has exited). Never run a foreground sleep: the Desktop Code tab blocks it. As a fallback where Monitor isn't available, re-read the output file at spaced intervals, each read its own tool call, never a tight loop. Stop waiting when one of these happens:
- The first line has a
status: it is the final line. Every check that runs before the page (missing_driver,name_taken,no_store,stale_install, and the other refusals), and the wholessopath, prints that one line and exits. Skip step 3 and go to step 4 with it. - The first line has a
url({"url": "http://127.0.0.1:<port>/<token>/", "expires_in": 300, "pid": <n>}): the page is listening, usually within a second. Go to step 3. - The background task has exited with no line, or, on the password path, about 15 seconds pass with no line: the helper failed before it could print (an import error, say, which goes to stderr only). Stop the task if it is still running (below), show the last stderr line in one sentence, and ask a card, header
Next step:Try again(step 2 again) /Use a file instead (manual)(0a.4).
With "auth": "sso" (auth: sso) there is no 15-second limit. The helper tests the connection before it prints anything, and that test can open a browser sign-in (Snowflake's SSO, say) that waits for the person. So tell the person once, when you start the helper, that a browser sign-in may open and that you are waiting for it to finish, then wait until the helper exits, up to 5 minutes, with the same Monitor watch. Don't repeat the line while waiting. Past 5 minutes with no exit, stop the task (below) and ask the Next step card above.
Don't run the helper in the foreground: it would hold the turn until the page is submitted, and the link would never reach the person. Where background commands aren't available, use the file path (0a.4) instead.
3. Post the link as a clickable markdown link, with this sentence and how long it lasts:
Enter your password. Enter the password on this page; it goes to your keychain, not the chat. The link expires after 5 minutes.
(On Windows say "Windows Credential Manager" in place of "your keychain".) Then a card, so the link isn't missed (a line of chat is easy to scroll past; a live run showed exactly that). AskUserQuestion, one question, header Password: "Enter the password on the page at http://127.0.0.1: Options: I've saved it / New link / Use a file instead (manual).
- I've saved it → read the helper's output: a final line is there → step 4. None yet → say the page hasn't been submitted, and ask the card again.
- New link → stop the running helper (below) and start step 2 again with the same spec.
- Use a file instead (manual) → stop the helper, then 0a.4.
The helper exits when the page is submitted or the 5 minutes pass, and that exit also brings you back if the card is still open: go to step 4 and don't ask the card again. Never wait silently: if the person writes before the helper is done, answer, and remind them the link is still open. If they want to stop, stop the background task with TaskStop and its task id (the helper then takes back whatever it stored), and show the database-type card again. Where TaskStop isn't available, on macOS and Linux kill <pid> with the pid from the helper's first line stops it the same way (it asks for permission; kill sends SIGTERM, and the helper takes back whatever it stored). On Windows, and without a pid (the sso path prints none), the helper is left to stop by itself when its 5 minutes are up: say so, and wait for its exit before starting it again.
4. Read the final line of the output when the helper exits, and act on it. The exit is what you wait for after the link is posted: the Monitor tool watching the task until it exits (or, as the fallback, spaced re-reads of the output file), never a foreground sleep; the background task's exit notice also brings you back. Exit code is 0 for every outcome; status (and a refusal's reason) says what happened, and detail is the one line to show the person. Each outcome gets one sentence plus the next card:
| final line | say | next |
|---|---|---|
connected |
"Connected to <name>. The password is in your keychain." (or the Windows store) |
Run setup_pgauth.py --all (as in 0a.10) and continue to Phase 1. |
connect_failed |
detail (why it failed). Nothing was kept: the helper removed the section and the stored password. |
Card Next step: Try again (the same fields, a new link; the person may have mistyped the password) / Change the connection details (0a.4c again) / Use a file instead (manual) (0a.4). |
expired |
"The link expired before the page was submitted; nothing was saved." | Card Next step: New link (step 2 again, same spec) / Use a file instead (manual). |
missing_driver |
detail, which names package. |
Card Driver: Install <package> (with the real package names) / Not now. On the press, install into the interpreter scripts/py uses: bash "${CLAUDE_PLUGIN_ROOT}/scripts/py" -m pip install --user <package> (unquoted: package can hold two names, duckdb pytz), then step 2 again. If pip fails, show its last line and offer Try again / Not now. Not now: stop with "Connect again when you're ready to install it." |
refused, no_store |
detail (agami's keyring library isn't set up for the OS store yet). |
Card Secure store: Set up secure storage / Use a file instead (manual). The first runs bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install (it adds keyring on macOS and Windows), then step 2 again. |
refused, stale_install |
detail (the agami-core this Python has is too old for the store). |
Card Update: Update agami (runs bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install, then step 2 again) / Use a file instead (manual). |
refused, name_taken or saved_password_exists |
detail (the name is in use here, or the OS store already holds a password under it). |
The name card (0a.3) again, then a new spec and step 2. |
refused, bad_name |
detail. |
The name card (0a.3) again. |
refused, bad_field |
detail (a field the credentials file can't hold). |
The connection fields card (0a.4c) again. |
refused, bad_spec |
Nothing to the person: the spec file you wrote is unreadable. | Rewrite it (step 1) and run step 2 again, once. A second bad_spec: say connecting failed and offer Use a file instead (manual). |
refused, unreadable_credentials or linked_credentials |
detail (the credentials file under <artifacts_dir>/local/ can't be parsed, or it or local/ is a link). |
Card Next step: I've fixed it (step 2 again) / Stop. Never open or print the file: it can hold passwords. |
refused, unsupported_os |
detail. |
The file path: 0a.4, then 0a.9. |
refused, not_replaceable |
detail (--replace was run for a profile that doesn't exist or doesn't keep its password in the OS store). |
Connect it as a new profile: the name card (0a.3), then step 2 without --replace. |
refused, store_error or write_failed |
detail (the store or the credentials file refused the write; nothing was kept). |
Card Next step: Try again (step 2) / Use a file instead (manual). |
Use a file instead (manual) always means 0a.4 → 0a.9 → 0a.10, the same as Linux. A line that is not one of these, or no final line at all: show the last line of output and offer Try again / Use a file instead (manual). Delete the spec file once the helper has exited.
On connected (the connection test passed), mark the step done and refresh the task list (shared/task-list.md):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" steps "<root>" --mark connect=done
0a.4 — Write <artifacts_dir>/local/credentials.example
The file path: Linux and any system without a secure store, Databricks on every system, and whoever picks Use a file instead (manual) in 0a.4k. The person types the password into the file themselves, so it never passes through the chat.
Use the Write tool. Shared header first, then the $DB_TYPE body with [$PROFILE_NAME] as the section.
Header:
# <artifacts_dir>/local/credentials.example
# Fill in your values below and save, then press "I've filled it in" in the chat.
# agami moves this file to <artifacts_dir>/local/credentials and chmod-600s it for you — no
# manual save or chmod needed. (Don't rename it yourself.)
# agami only runs read-only SELECT queries, so a read-only database user is all it needs
# (and the safest thing to connect). Copy-paste GRANT SQL for your database:
# plugins/agami/shared/readonly-grants.md — or ask agami for "the read-only grant".
# Format reference: plugins/agami/shared/credentials-format.md
# Switch profiles with AGAMI_PROFILE=<name>.
Bodies — postgres, redshift, snowflake, mysql, bigquery, sqlite are unchanged from shared/credentials-format.md (URL-form first for Postgres/MySQL/Redshift; account fields for Snowflake; project+service_account_path for BigQuery; path for SQLite). The new dialects:
# SQL Server / Azure SQL.
[$PROFILE_NAME]
type = sqlserver
host = your-server.database.windows.net
port = 1433
database = your-database
user = your-username
password = your-password
# Oracle.
[$PROFILE_NAME]
type = oracle
host = your-host.example.com
port = 1521
service_name = ORCLPDB1
user = your-username
password = your-password
# OR a full DSN: dsn = host:1521/ORCLPDB1
# Databricks SQL warehouse.
[$PROFILE_NAME]
type = databricks
host = your-workspace.cloud.databricks.com
http_path = /sql/1.0/warehouses/abc123
token = dapiXXXXXXXXXXXX
# catalog = main # optional Unity Catalog
# Trino / Presto.
[$PROFILE_NAME]
type = trino
host = your-coordinator.example.com
port = 8080
user = your-username
catalog = your_catalog
schema = your_schema
# password = ... # uncomment for HTTPS + basic auth
# DuckDB (local file or in-memory).
[$PROFILE_NAME]
type = duckdb
path = /absolute/path/to/your.duckdb
Always finish with the additional-profiles hint (one commented block):
# Add more profiles by appending another [section]. Switch with AGAMI_PROFILE=<name>.
# [staging]
# type = postgres
# url = postgresql://readonly:pass@staging-db.example.com:5432/mydb
For BigQuery / Databricks / any key-or-token file: remind the user to chmod 600 it.
0a.5 — Resolve the agami interpreter + detect tools
<python3> = data.interpreter.python3, written out in full, from the Phase-0 connect_resolve.py call — the ONE Python agami uses for the model and DB connections (introspection always runs python -m execute_sql under it on every tier, so the DB driver must live in it). It's already the scored pick — the candidate that has pydantic+sqlglot+pyyaml AND the $DB_TYPE driver — so there's no guessing and the user sets nothing. Re-run bash "${CLAUDE_PLUGIN_ROOT}/scripts/py" connect_resolve.py --db-type <db_type> now that the DB type is known, so the interpreter is scored against the right driver and native tools are refreshed. It records as tool_paths.python3 in 0a.7. (AGAMI_PYTHON is honored as a first-priority override but is never required.)
Native CLIs (optional fast path for queries — introspection doesn't use them) are in data.tools (psql/mysql/snowsql/sqlite3/duckdb/bq, null if absent), detected with which only. Forbidden elsewhere: pgrep/ps/lsof/find //ls /Applications/port scans.
If data.interpreter.has_driver is false the $DB_TYPE driver isn't in <python3> yet — confirm via AskUserQuestion, then "<python3>" -m pip install --user <package> from the table, where <python3> is data.interpreter.python3 written out in full (probe was already done in <python3> by connect_resolve.py):
$DB_TYPE |
probe ("<python3>" -c '…') |
pip package |
|---|---|---|
| postgres / redshift | import psycopg2 |
psycopg2-binary |
| mysql | import pymysql |
pymysql |
| snowflake | import snowflake.connector |
snowflake-connector-python |
| bigquery | import google.cloud.bigquery |
google-cloud-bigquery |
| sqlserver | import pymssql |
pymssql |
| oracle | import oracledb |
oracledb |
| databricks | from databricks import sql |
databricks-sql-connector |
| trino | import trino |
trino |
| duckdb | import duckdb, pytz |
duckdb pytz |
| sqlite | stdlib — always present | — |
duckdb needs
pytzto materializeTIMESTAMP WITH TIME ZONEvalues into Python — without it a query that selects a timestamptz column fails at runtime (Required module 'pytz' failed to import), so it's part of the driver install, not optional.
If the driver is missing, confirm via AskUserQuestion, then "<python3>" -m pip install --user <package> (plain pip install fallback). Same "never install silently" convention as the model deps (0a.5b). Do this for <python3> so sm introspect connects on the first try.
0a.5b — Ensure the semantic-model dependencies
This runs first, right after 0a.0: saving the folder (0a.6), setting it up (0a.1) and writing .config (0a.7) need agami's library, and none of them installs it (each stops with exit code 12 and the install step instead), so the person agrees to the install before anything is set up. The model (introspection, validation, traversal, curation — everything the sm wrapper drives) needs pydantic + sqlglot + pyyaml in the interpreter agami uses. The resolve step already checked the interpreter it picked: data.interpreter.core_ready in its output (preflight step 1) says whether agami's library is ready in it (the deps, the agami-core package itself and this plugin's version), so no command is needed here. Decide on core_ready, never on has_model_deps alone: the deps can be there with no agami-core, and then every setup call stops with exit code 12.
If it is ready, continue. If missing, confirm via AskUserQuestion before installing (same convention as the DB-driver install above — agami never installs silently):
agami needs the agami-core package (which pulls
pydantic,sqlglot,pyyaml) to build and read the semantic model. Install it now? (one-time, user-site —pip install --user)
On Yes: bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install — the sm launcher is the single place that installs the agami-core library into the resolved interpreter (editable from a dev checkout, else the published package via PyPI or pinned git — so it works in a marketplace install with no packages/ dir), and everything (python -m execute_sql / python -m semantic_model.cli / sm) then resolves it. On No: stop with "Can't build the model without it — re-run when you're ready to install." — don't proceed to introspect.
(The sm wrapper also self-installs these on first use as a safety net, but doing it here makes it explicit, confirmed, and at a predictable moment rather than mid-introspection.)
0a.6 — Ask for <artifacts_dir> (first run only)
This runs before 0a.1, because 0a.1 and 0a.7 act only on the folder agami has saved. The folder is chosen once, on the very first onboarding, and reused for every profile thereafter. Whether it is already set is in the resolve step's output (preflight step 1): when data.artifacts_dir_source is env (AGAMI_ARTIFACTS_DIR) or pointer (the saved pointer), or data.config.present is true, skip this question entirely — reuse data.artifacts_dir and continue to 0a.1. Never read or list the pointer file yourself. Only a brand-new install (artifacts_dir_source is default and no .config) reaches the question below. This guarantees a second/third database lands as a sibling inside the same folder rather than re-prompting (and risking a fragmented, multi-folder setup).
The options follow the operating system the session's environment names (as at the top of Phase 0a). Then AskUserQuestion with the two defaults for that OS as named options (Recommended first). The auto-provided Other lets the user type any absolute path — so this both gives sensible options and allows a full custom path:
Where should agami save your semantic model, examples, and preferences? This is the parent for ALL profiles — each lands in
<artifacts_dir>/<profile>/. It's non-secret (no credentials) — point it inside a git repo to share the tuned model with your team. Credentials stay in<artifacts_dir>/local/regardless.
| OS | Option 1 — Recommended | Option 2 |
|---|---|---|
| macOS | ~/agami-artifacts |
~/Documents/agami-artifacts |
| Linux | ~/agami-artifacts |
~/Documents/agami-artifacts |
| Windows | %USERPROFILE%\agami-artifacts |
%USERPROFILE%\Documents\agami-artifacts |
(For Other, suggest a team repo path as the example, e.g. ~/code/acme-data/agami.) Expand ~ / %USERPROFILE% to an absolute path, then save the choice, whichever option it is, with one call (it checks the folder is absolute, not a file and not inside <artifacts_dir>/local/, and writes the pointer at <home>/.config/agami/path so future sessions find it; never write the pointer yourself):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" choose-folder "<artifacts_dir>"
An error is said back and the same card asked again. Then 0a.1; 0a.7 records the folder in .config.
0a.7 — Write <artifacts_dir>/local/.config
One call, which checks each value and keeps every other key in the file (written 0600):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" set-config "<artifacts_dir>" --tier <tier> --active-profile <profile> --python3 "<python3>" --tool <tool>="<tool_path>"
<tier> is cli, duckdb or python; --tool names the native query tool the tier uses (psql, mysql, snowsql, sqlite3 or duckdb) with its absolute path, left out for the python tier. python3 MUST be the <python3> resolved in 0a.5 (the interpreter that has both the model deps and the DB driver) — sm and the introspection engine read it from here, so recording the wrong one reintroduces the interpreter mismatch. Never write .config with the Write tool.
The database's folder is known from here, <root> = <artifacts_dir>/<profile>: mark the step started and refresh the task list (shared/task-list.md):
bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" steps "<root>" --mark connect=in_progress
0a.8 — Seed <artifacts_dir>/USER_MEMORY.md if missing
Write the default seed (per shared/user-memory-format.md) with the Write tool, which makes the folder; the file comes out readable by others under the usual umask, as this non-secret file should, so it needs no chmod. Don't overwrite. Migrate a v1.1 <artifacts_dir>/local/USER_MEMORY.md if present.
Then write what 0a.0 held (the folder and the interpreter exist now): the company (1.4 A's two writes) and, when it was given, the personal-data setting (sm set-personal-data). The fiscal year waits for 1.7.
0a.9 — Hand-off, then a reply that waits for the file
Show the summary; it ends the turn with the reply line below (a summary before a card in the same message does not reach the person, long-text.md).
✓ <artifacts_dir>/local/ ready (chmod 700)
✓ Credentials template → <artifacts_dir>/local/credentials.example
✓ Tool detected: <tool> (<tier>)
✓ Artifacts dir: <resolved path>
Open <artifacts_dir>/local/credentials.example, fill in your connection details and save it
(keep the filename as-is — don't rename it). I'll secure the file and run the full
introspect → enrich → seed flow.
Tip: agami only runs read-only queries, so a read-only database user is all it needs
(and safest). Want the exact GRANT SQL for your database? Just ask.
The reply line: Reply "I've filled it in" once the file is saved, or "show me the file again". Handle the reply as the choices below; words that mean one of them count as it:
| label | description | then |
|---|---|---|
I've filled it in |
Secure the file and connect | 0a.10 |
Show me the file again |
Where the file is and what to fill in | Print the path and the field names of the [$PROFILE_NAME] section from the template you wrote (from your own copy, never by reading the file: once filled in it holds the password), then the reply line again. |
The reply is the wait: don't continue to Phase 1 until I've filled it in is said (or, in a later session, until the person comes back with any data question and preflight returns promote).
Show the read-only Tip line only for dialects with a user/role concept (postgres,
redshift, mysql, snowflake, sqlserver, oracle, databricks, trino); omit it for
sqlite / duckdb (file-based, no user) and when BigQuery auth is ADC. If the user asks for the
grant, read shared/readonly-grants.md, pick the $DB_TYPE
block, and fill in whatever <…> placeholders it uses (e.g. <db> / <schema> / <warehouse> /
<catalog> / <project> / <dataset>) from the values they entered.
0a.10 — On re-entr
Files (agami-core)
-
SKILL.md 280 KB
--- name: agami-connect description: "End-to-end database connection for agami: sets up credentials on first run (DB-type picker → writes <artifacts_dir>/local/credentials.example for the user to fill in), then introspects the live DB directly into the agami semantic model (subject areas, tables, columns, relationships with join cardinality, deep-table column groups, sensitive-column flags) under <artifacts_dir>/<profile>/. The structural model is built deterministically by the agami-core semantic_model package (catalog mode, or a probe-mode fallback when the catalog is locked down); the skill then layers LLM enrichment (descriptions, entities, metrics) and seeds EXPLAIN-validated NL→SQL examples. Every model write is gated by the semantic-model validator — no breaking model is ever persisted." when_to_use: "Run when the user installs the plugin for the first time, asks 'how do I set up agami' / 'connect to my database' / 'introspect my database' / 'introspect the schema' / 'reload schema' / 'add a new database', wants to try agami WITHOUT a database ('I don't have a database', 'try the sample', 'use the sample data', 'demo data'), or after the user changes their schema and wants the model refreshed. Also auto-invoked by agami-query the first time it runs (when the semantic model is missing). This skill handles credential setup, introspection, enrichment, and seed-example validation — one entry point for everything before the user can query. The sample-database path (Phase 0s) needs no connection and copies in a ready, queryable model." argument-hint: "[sample | reintrospect | profile NAME]" --- # agami connect **Before suggesting any slash command in chat, read [`shared/invocation-conventions.md`](../../shared/invocation-conventions.md).** Agami slash commands: `/agami-connect`, `/agami-query`, `/agami-model`, `/agami-save-correction`, `/agami-reconcile`. (`/agami-model` is also the trust-review surface — its Review tab absorbed the former `/agami-review`.) Never write the un-prefixed forms (`/init`, `/connect`, etc.) or colon forms (`/agami:connect`) — those don't exist. For chat replies, prefer natural language ("say 'reload the schema'", "say 'introspect my database'") — the `when_to_use` matcher routes correctly without an explicit slash command. You are setting up the agami **semantic model** for the user's database. Goal: by the end there is a validated semantic model at `<artifacts_dir>/<profile>/` (`datasource.yaml` + `subject_areas/<area>/…` + `datasources/<connection>/storage.yaml`), a seeded examples library at `<artifacts_dir>/<profile>/prompt_examples/<area>/examples.yaml`, an `datasource.md` the user can edit, and the user has seen one demo query execute end-to-end. **The structural model is built by a deterministic engine, not hand-authored.** `sm introspect` (run as Phase 1.7 shows) introspects the live DB across all supported dialects — **PostgreSQL (incl. Supabase / Redshift), MySQL/MariaDB, Snowflake, BigQuery, SQL Server, Oracle, Databricks, Trino/Presto, DuckDB, SQLite** — into the model: storage connection, proposed subject areas, tables, columns + types, primary-key grain, foreign-key relationships **with join cardinality**, `column_groups` on wide tables, and `sensitive` flags on PII. When the catalog (`information_schema` / PRAGMA / data-dictionary) is reachable it runs in **catalog mode**; when a locked-down role denies the catalog it falls back **per-capability to probe mode** (describe via a zero-row header, infer types from a value sample, grain from uniqueness probes, FKs from name+overlap) and everything inferred lands `unreviewed` for sign-off. Your job is the layer the engine can't do: **enrichment** (prose descriptions, entities, metrics, caveats) and **curation** (subject-area boundaries, trust review). **If an `sm` call exits 12, agami's library is older than the plugin:** run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install` (the person approves it), then repeat the call. It is not "no model" (exit 3): never send the person to agami-connect for it. For the model format: [`semantic_model/__init__.py`](../../../../packages/agami-core/src/semantic_model/__init__.py) (layout) and the Pydantic models in `packages/agami-core/src/semantic_model/models.py`. For credentials: [`shared/credentials-format.md`](../../shared/credentials-format.md). For connection method + local execution: [`shared/connection-reference.md`](../../shared/connection-reference.md). For DB error classification: [`shared/db_error_classifier.md`](../../shared/db_error_classifier.md). For every decision card and result table: [`shared/question-cards.md`](../../shared/question-cards.md). ## Conversation style - **Combine acknowledge + next question** — don't waste turns on "Got it!" - **Use AskUserQuestion for every Yes/No/Skip** — never inline-bullet options. Where AskUserQuestion is unavailable, ask the same as a short numbered list ([`shared/question-cards.md`](../../shared/question-cards.md) rule 7). Use `(Recommended)` only when there's a genuine recommendation. For fact-of-environment questions ("which database type?", "which schemas?"), don't mark any option Recommended — the user picks what they have. - **Every multiSelect needs an explicit "none / continue" option** — `AskUserQuestion` cannot be submitted with zero boxes checked, so any multiSelect where "pick nothing" is a valid answer MUST offer a selectable "Nothing — continue" (or "Keep everything") option. Never phrase the prompt as "leave all unchecked" — that's unsubmittable and traps the user. - **Ask the business, decide the plumbing** ([`shared/question-cards.md`](../../shared/question-cards.md#9-a-card-asks-what-the-data-means-to-the-business-never-plumbing) rule 9): a card asks only what the data means to the business, in plain words with an example. Batches, `--append`, `--no-safety`, mapping thresholds and the like are yours to decide, conservatively, and to report in one line. A card never names a file or table without saying what it is. Before signing answers that came back the same down a whole column of a page or sheet, confirm in one line ([rule 10](../../shared/question-cards.md#10-answers-filled-down-are-confirmed-before-they-are-signed)). - **Keep the user oriented** — print one-line progress markers between phases (`✓ Introspected 12 tables`, `✓ Validator passed`, `✓ Generated 10 examples`). - **Plain voice — state what happened, never how impressive it is.** Progress markers, todo labels, and narration describe the action and the result; they do NOT editorialize. Banned: "wow moment", "magic", "watch this", "the exciting part", "you'll love this", exclamation hype. The reader is a data professional — a query running correctly speaks for itself. Say *"Running the first query"*, not *"Now the wow moment"*. ## Progress tracking — the onboarding steps, shown the whole way This is a multi-phase skill, with cards in between. **The very first action on every invocation is to show the onboarding steps as a task list, and to keep it current**, so the person always knows where they are and what's left. Once the database's folder exists, the list is drawn from `sm steps`, which prints every step with its status and its numbers read from disk; how and when to run it, and where the list goes, is in [shared/task-list.md](../../shared/task-list.md). Each phase below marks its own step when it starts and ends. The same steps every run, in the person's words (no "introspect", "enrich" or "NL→SQL"): ``` 1. Connect your database 2. Tell agami about your data 3. Pick the tables 4. Read the tables and joins 5. Describe columns and add metrics 6. Answer what the data can't settle 7. Sign off definitions and hide personal data 8. Write and check example questions 9. Check your reports 10. Summary and first question ``` Leave out a step that won't run (6 when "Ask me as you go" wasn't picked in 1.5; 9 when no reports were shared in 1.5; 3 with a model spec workbook, which names the tables): mark it `skipped`, and `sm steps` leaves it out of the list; never add your own working steps to this list. **When a step finishes, add its numbers to its label**, so the list reads as a running summary: *"Read the tables and joins — 21 tables, 19 joins"*, *"Describe columns and add metrics — 93% described, 7 metrics"*, *"Sign off definitions and hide personal data — 5 of 7 signed"*. The label with its numbers is the step's line in the `list` that `sm steps` prints, copied as printed without its mark, never typed by hand and never an estimate; a step with nothing to count keeps its plain label. **While a long step runs, its label carries the live count too** (*"Read the tables and joins — 30 of 52 tables"*), from the same line, which `sm progress --wait` prints in its own `list` on every pass, so the list shows movement during a wait and not only at the end. **Mark each step in progress when it starts and done the moment it ends**, exactly one in progress at a time, and keep it in progress while a card for that step is waiting, so the list shows where the person is while they decide. **Don't seed it again if the list already holds these steps** (the skill is resuming after a hand-off, a password page or a file wait): run `sm steps "<root>"` first and show what it prints ([shared/task-list.md](../../shared/task-list.md), resuming). When `$ARGUMENTS == reintrospect`, the list restarts at the first step this run marks started (step 2, when Phase 1 begins): `sm steps` reopens that step and every step after it, and keeps the steps before it done. --- ## Phase −1: Plan-mode check Run the detection + ask logic from [`shared/plan-mode-check.md`](../../shared/plan-mode-check.md). agami-connect needs Bash (introspection) and Write (model files) — both blocked in plan mode. **If plan mode is active and the user stays in plan mode** (or the skill is invoked under plan mode with no prompt): refuse with the one-liner below and **end the turn**. DO NOT write a plan file. DO NOT call `ExitPlanMode`. > I can't introspect in plan mode — switch to **Auto** or **Edit Automatically** mode (Shift+Tab to cycle) and re-invoke me. Introspection, enrichment, and the demo query all need write access to `<artifacts_dir>/<profile>/`. If plan mode is not active, skip silently. --- ## Phase 0: Preflight ### HARD RULES — read before doing anything Non-negotiable. They override every other instruction here when they conflict. 1. **Connect ONLY to the host/port/database/user/password in `<artifacts_dir>/local/credentials`.** That file is the sole credential source — there is no env-var bypass. Never connect to anything else. Never probe `localhost` unless the credentials say so. Never substitute defaults for missing fields. 2. **Never ask for a password in chat.** Nor any other secret: a password, an access token, a key (or a key file's contents), or a DSN that contains a password. Not even temporarily, and never echo one back. The non-secret fields (host, port, database, user, account, warehouse, a file path) ARE asked in chat, on the connection cards in 0a.4c: they are not secret, they already appear in the credentials file in plain text, and a card is faster than editing a file. The secret goes only through a path that keeps it out of the chat, the transcript, and your context: on macOS and Windows the one-time local page of **0a.4k** (it goes straight to the OS credential store), on Linux (and for a Databricks token anywhere) the `credentials.example` file of **0a.4** that the person fills in themselves. If the person types a secret into the chat anyway, don't use or repeat it: say it should not be shared in chat, suggest they change it, and carry on with the page or the file. 3. **Never scan or guess.** No `pgrep`, `ps`, `lsof`, `find /`, `ls /Applications`, no port-listener scans, no testing connections to common hostnames. The only acceptable Bash probes here are `which <tool>` and `bash "${CLAUDE_PLUGIN_ROOT}/scripts/py" -c 'import <module>'`. 4. **If credentials are missing for the active profile, run Phase 0a.** It ends connected (the password page, 0a.4k) or with a card that waits for the filled-in file (0a.9). A person who closes the chat instead can come back later with any data question — `agami-query` auto-invokes us and 0a.10 picks the file up. 5. **NEVER put a credential on a Bash command line** — no `export PGPASSWORD=…`, no `psql -W <pw>`, no heredoc that interpolates a secret. Hosts render Bash calls in chat; anything on the line leaks. Runtime queries use the auth files from `scripts/setup_pgauth.py` (psql/mysql) or `python -m execute_sql` (every driver, reads `<artifacts_dir>/local/credentials` itself). See [`shared/connection-reference.md → HARD RULES`](../../shared/connection-reference.md). 6. **Run each agami command as its own Bash call: `bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" <verb> …` with every path written out in full.** Never put a variable assignment, a pipe, `;`, `&&`, a redirect or a filter on the line, and never run two agami commands in one call. A line written any other way always stops to ask the person for permission; written this way agami's own hook approves the read-only commands and scratch files without a prompt, and every other command asks as usual. Read the whole output: the commands print only what you need. Where a command starts with `AGAMI_SCRATCH_ONLY=1` (and `AGAMI_SQL_MAX_ROWS=200000` before it on `discover` and `introspect`), copy that prefix exactly: it holds every file the call names to agami's scratch folder. `<root>` is the database's model folder, `<artifacts_dir>/<profile>`, written out in full; the artifacts folder is preflight step 1's `artifacts_dir`, never read from the pointer file; scratch files go only in `<artifacts_dir>/local/tmp/`, named `agami-…`, never `/tmp`, and are written with the Write tool ([`shared/invocation-conventions.md`](../../shared/invocation-conventions.md)). The person's own words (a company name, a description, a question) go to `sm` through a file the same way (`--name-file`, `--description-file`, `--question-file`), never on the command line. 7. **Do what the engine says.** When an agami command's output has `say`, post it as written; when it has `then`, do that next. If you reach for a command that doesn't fit, stop and re-read this section. ### Preflight steps 0. **Sample-path short-circuit (check FIRST, before resolving any profile).** If the user explicitly asked for the sample — `$ARGUMENTS` is `sample`, or they said *"try the sample"* / *"I don't have a database"* / *"use the sample (or example) data"* / *"demo data"* — then bind `$PROFILE_NAME = agami-example`, `$DB_TYPE = sample`, and **go straight to [Phase 0s](#phase-0s-sample-database-bootstrap-no-connection)**. Do this **regardless of any existing `active_profile` or onboarded profiles** — the sample is a deliberate, explicit choice and must not be intercepted by another profile's credential/existing-model checks. (A returning person also gets "Try the sample data" on the start card in step 1a; this short-circuit covers the request that already says so.) If `agami-example` is already set up, Phase 0s sends them to the demo. Only fall through to step 1 when there's **no** sample signal. 1. **Resolve the environment** — `bash "${CLAUDE_PLUGIN_ROOT}/scripts/py" connect_resolve.py [--db-type <t>] [--profile <p>]` prints `{data, anomalies}` (self-describing JSON): profile, artifacts_dir, the `[<profile>]` credentials section + chmod, the cached config, `interpreter.python3` (the one Python `sm`, `py` and the install all use — use it everywhere; what it lacks, `core_ready` and `has_driver` say), native `tools`, and a `next` decision. Branch on `data.next`: **`ready`** → the start card for a returning person (step 1a); a reload or re-introspect request skips the card and goes straight to Phase 1 with `reintrospect`; **`build`** → the database's credentials are saved but it has no model yet (the build never ran or never finished): there is nothing to ask yet, so show no start card and never offer "Ask a question"; say in one line *"`<database>` is connected but not built yet, so I'll build it now."* and go straight to Phase 1 (a fresh build, not `reintrospect`), unless the request already names another action (the sample, or connecting a different database); **`promote`** → run 0a.10 to promote the filled template, then continue; **`bootstrap`** → the first-run start card (step 1a), then Phase 0a. On a first-time bootstrap `data.profile` is **`null`** (`profile_source: "default"`) — there's no profile yet, so narrate it **without a name**: *"No credentials yet — first-time setup."* (Never say "profile `main`" — the user names their profile in 0a.3.) Only when `data.profile` is non-null (a `bootstrap` for an explicitly-named/env profile) may you name it. Surface `anomalies`. **`agami_python_lacks` comes first and stops the run:** the `$AGAMI_PYTHON` the person set lacks the model deps or the driver, and agami uses that Python and no other, so say its `detail` (the path, what it lacks and the exact install line) before anything else, and go no further until they have run it or changed `AGAMI_PYTHON`; then resolve again. The others (e.g. `credentials_world_readable` → offer `chmod 600`; `library_older_than_plugin` → offer `bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install`, or the `AGAMI_PYTHON` fix it names; `agami_python_cannot_be_brought_current` → the `$AGAMI_PYTHON` the user set has no pip and an old or missing agami-core, so say so; `env_profile_has_no_model` → `AGAMI_PROFILE` names a database with no model while others have one: say its `detail` in one line before the start card, and offer the databases it lists rather than a new connection under that name, unless the person asked to connect one). `interpreter.chosen_because` says why that Python was picked, and a candidate passed over carries a `reason`; never substitute a `missing_fields` value — surface "missing field X for profile Y" and stop. 1a. **The start card** (conventions: [`shared/question-cards.md`](../../shared/question-cards.md)). One AskUserQuestion, one question, header `Start`. Skip it when the request already names the action: `$ARGUMENTS` is `reintrospect` or `profile NAME`, the person asked to reload or re-introspect, to add a new database (go to Phase 0a), or `agami-query` invoked this skill because a model is missing (go to Phase 0a). - **First run** (`data.next` is `bootstrap`, nothing connected yet). Question: *"How do you want to start?"* No option is marked Recommended: whether there is a database to connect is a fact about the person's setup. | label | description | then | |---|---|---| | `Connect a database` | Your own database; the password never goes through the chat | Phase 0a | | `Try the sample data` | A small demo store, no connection needed | Phase 0s | - **Connected but not built** (`data.next` is `build`). No start card: go straight into the build (step 1). A database with no model has nothing to ask, so `Ask a question` is never offered for it. - **Returning** (`data.next` is `ready`: a database is already connected and built). Question: *"What would you like to do?"* | label | description | then | |---|---|---| | `Ask a question (Recommended)` | Ask `<active database>` something | Hand to [agami-query](../agami-query/SKILL.md). A question typed in "Other" goes straight there. Picked with no text: offer a card of up to 4 questions taken from that database's seed examples (`prompt_examples/`), with "Other" for their own. | | `Reload the schema` | Pick up new or changed tables, keeping descriptions, metrics and sign-offs | Phase 1 as `reintrospect` (the 1.1 Re-introspect path; 2e previews, then writes). | | `Connect another database` | Add a different database alongside this one | 1.1a first (same company or a different one), then Phase 0a (the new database gets its own name in 0a.3). | | `Try the sample data` | A small demo store, no connection needed | Phase 0s | **An empty database gets no recommendation to ask it.** When every table in the active database's `sm model-tree` has `rows` of 0, the first option is `Ask a question` without "(Recommended)", its description says *"<database> has no rows, so answers will be empty"*, and `Connect another database` is marked **(Recommended)** instead. Route "Other" text by what it asks for. An action goes to that action: re-introspect, reload or refresh the schema → `Reload the schema`; add a schema that lives in the same database → `Reload the schema` with the schema selection in 1.3 widened to the old and new schemas (see the note under 1.1: same database, another schema is a re-introspect, never a new database); review or sign off the model, edit descriptions, exclude tables → [agami-model](../agami-model/SKILL.md); add or connect a different database → `Connect another database`; answer the open questions, or what the data can't settle → [2g](#2g--ask-what-the-data-cant-settle) on the active database. Only a question goes to agami-query. When the text could be either (a schema name alone, say), ask which with a card rather than guess. This card replaces the 1.1 menu for a returning person; don't ask 1.1 again after it. Say "database", never "profile", in the card and around it. 2. **Update-check (best-effort).** Run the probe from [`shared/version-check.md`](../../shared/version-check.md); surface a one-liner if a newer version exists. Never block on network failure. 3. If `$ARGUMENTS` is `reintrospect`: re-introspect from scratch, but **preserve hand-edits** (descriptions, entities, metrics, caveats, trust sign-offs). The engine writes the structural skeleton; merge it over the existing enrichment rather than discarding it (see Phase 2's reintrospect note). --- ## Phase 0a: First-time credential bootstrap **Runs when preflight step 1 returns `next: bootstrap` (no credentials for the profile) and the person picked "Connect a database", or when they picked "Connect another database".** If `<artifacts_dir>/local/credentials` already has the `[<profile>]` section for the database being connected, **skip Phase 0a entirely.** **Two paths, chosen by the operating system**, which the session's environment already names (the platform: `darwin` is macOS, `win32` is Windows, `linux` is Linux); don't run a command to find it: - **macOS and Windows: the password page.** **0a.0** → 0a.5b → 0a.6 → 0a.1 → 0a.2 → **0a.4c** (connection fields card) → 0a.3 (the name, offering the database's own name) → 0a.5 → 0a.7 → 0a.8 → **0a.4k** (the password page) → Phase 1. No file to edit and nothing to paste. The page needs the interpreter, agami-core (with `keyring`) and the artifacts folder in place, which is why 0a.5–0a.8 run before it. - **Linux and anything else, and Databricks on every system** (its secret is a `token`, and the page stores a `password`): the file. **0a.0** → 0a.5b → 0a.6 → 0a.1 → 0a.2 → 0a.3 → **0a.4** (`credentials.example`) → 0a.5 → 0a.7 → 0a.8 → **0a.9** (a card waits for the filled-in file) → 0a.10 → Phase 1. ### 0a.0 — Before you start: what to have ready, then the organisation and the source system **First, before the database-type card**, say in one short message what helps to have to hand, so nobody is asked mid-build for something they could have fetched up front. None of it is required: > *Before we connect, it helps to have these to hand (none is required):* > 1. *What your organisation does, in a sentence or two.* > 2. *What system the data comes from (a product such as ServiceNow or Salesforce, or your own application), and anything about the database: when your fiscal year starts, what currency amounts are in, whether the warehouse already controls who sees personal data.* > 3. *Definitions of the tables and columns: a data dictionary, a spec workbook, a dbt or LookML project.* > 4. *Definitions of your metrics and business terms.* > 5. *The questions people ask. They become checked examples, and how many of them agami answers correctly is how you can tell the model is right.* Then ask 1 and 2 as their own first questions, on one card (two questions; leave the Company one out when it was already authored, as 1.4 A says): - **The Company question** is 1.4 A's `Company` card, asked here instead of after the connection. 1.4 A says what to write, and it is written once the folder exists (below). - **The Source question**, header `Source`: *"What system does this data come from? Add anything about the database too, e.g. "ServiceNow; fiscal year starts in July; amounts in USD". Type it in Other."* Options: **Our own application** (built in-house, no product dictionary) and **Not sure** (agami reads the database and works it out). No option is marked Recommended: it is a fact about their setup. **Both answers are hints, never copied verbatim into the model.** They steer the descriptions written in Phase 2 (a domain prior, like the narrative) and switch on product-specific help; no description, glossary entry or rule is the person's sentence pasted in. **Hold the answers; write nothing yet.** At this point there is no artifacts folder (0a.6 picks it) and no interpreter (0a.5 finds it), so `sm` can't run. Bind them now and write each where the list below says: the company and the personal-data setting **right after 0a.8**, when the folder and the interpreter exist; the fiscal year **after 1.7**, when `datasource.yaml` exists. Bind the Source answer: - **A named product** → `$SOURCE_SYSTEM`. When agami has a metadata preset for it (ServiceNow: `servicenow`), 2a.0 passes `--preset servicenow` to `sm enrich-metadata`, which reads the product's dictionary and choice tables straight from the database without modelling them. So **never add the preset's source tables (`sys_dictionary`, `sys_choice`, or a warehouse copy under another name) to 1.6's kept set**: 2a.0's `enrich-metadata --preset <name>` reads them directly, and kept they are modelled as ordinary tables. And 1.5's published-product-schema path is already on. Say it in one line: *"ServiceNow: I'll read its own data dictionary for the column meanings."* - **A fiscal year start, stated plainly** → `$FISCAL_START_MONTH` (1 to 12). After 1.7 write it with `bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" set-fiscal-year "<root>" --month <month>`, the same write 1.4 D makes, and skip 1.4 D's card. Anything vaguer ("our year is odd") is not a month: 1.4 D asks it. - **A currency, stated plainly** → `$CURRENCY_HINT`, a hint only: nothing is written now. 2d offers it as the currency for the money columns `sm suggest-units` finds (`sm set-units --currency <ISO code>`), and the person still agrees to that plan there. - **The warehouse already controls who sees personal data** (column- or row-level security, "our warehouse handles PII") → after 0a.8, before the build: `bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" set-personal-data "<artifacts_dir>" enforced_by_warehouse`. It is a build-only setting, kept in `<artifacts_dir>/local/.config` and never deployed. The build then flags nothing personal and Phase 4 skips the personal-data question. Say it in one line. `set-personal-data "<artifacts_dir>" flagged_by_agami` undoes it (a reload flags again). - **Our own application** / **Not sure** → nothing is written; the build works from the database. Items 3 to 5 are handed over on 1.5's context card (its `Definitions or a semantic layer` and `Questions people ask` options); the questions people ask go to `<artifacts_dir>/local/tmp/agami-asked-questions.txt` and become checked examples in Phase 5, as they do today. Don't ask for them here. **When Phase 0a is skipped** (the credentials already exist), ask this step at the start of 1.4 instead, on a first onboard of that database. Not on `reintrospect`. ### 0a.1 — Set up `<artifacts_dir>/local/` `<artifacts_dir>` is settled by now: 0a.6 chose it on a first run and saved it with `sm choose-folder`, and otherwise it is the resolve step's `data.artifacts_dir`. One call creates the folder, its private `local/` (0700) and scratch folder, and makes `<artifacts_dir>/.gitignore` ignore `local/` (no Write, Read or `mkdir` of your own): ```bash bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" init-local "<artifacts_dir>" ``` It works only on agami's own artifacts folder: an `error` naming another folder means 0a.6's `choose-folder` call hasn't run. It never installs anything: exit code 12 means agami's library isn't installed yet, so ask 0a.5b's card and run `sm install` first, then this call again. ### 0a.2 — Ask the database type **AskUserQuestion**, one question, header `DB type`, no `(Recommended)` — fact-of-environment. The sample data is on the start card (1a), not here. **Name the Other-only engines in the QUESTION PROMPT** so they're visibly supported — the auto-provided "Other" field can't carry its own description/examples, so the examples must live in the prompt. End the prompt with a line like: > *Something else — BigQuery, SQL Server, Oracle, Databricks, Trino/Presto, DuckDB, or SQLite? Choose **Other** and type it (a name or a file path).* | label | description | |---|---| | `PostgreSQL` | Postgres + compatible: Supabase, Neon, RDS, Aurora, Cloud SQL, Timescale, and **Amazon Redshift** (port 5439, SSL by default). | | `MySQL` | MySQL, MariaDB, RDS MySQL, PlanetScale. | | `Snowflake` | Snowflake. Account identifier instead of host. | | `Other (Other field)` | **BigQuery, SQL Server, Oracle, Databricks, Trino/Presto, DuckDB, SQLite**. | Bind `$DB_TYPE` ∈ `postgres | mysql | snowflake | bigquery | sqlserver | oracle | databricks | trino | duckdb | sqlite | dsn`. **Routing:** - **"sample" typed in Other** (or *"I don't have a database"*) → Phase 0s, as on the start card. - `PostgreSQL` → `postgres`; if the user later enters port `5439` or a `*.redshift.*.amazonaws.com` host, transparently re-bind to `redshift`. A `*.pooler.supabase.com` host stays `postgres` (Supabase is hosted Postgres). - `MySQL`/`Snowflake` → pass-through. `BigQuery` lives under **Other** now (or the user types it) → `bigquery`. - `Other` → parse the free-form input: a DSN scheme → derive `db_type` (if it carries a password, follow HARD RULE 2: don't use or repeat it, ask the fields on 0a.4c instead); `.db`/`.sqlite`/`.duckdb` suffix or absolute file path → SQLite or DuckDB; a named DB (`bigquery`, `sqlserver`/`mssql`, `oracle`, `databricks`, `trino`/`presto`, `duckdb`) → that dialect. Only refuse with "not supported yet" for engines outside the supported set above (e.g. MongoDB, Cassandra, ClickHouse). ### 0a.3 — Name the database (the person's choice) Ask the user to **name** this connection — don't pick for them. The name is how they'll switch databases later (`AGAMI_PROFILE=<name>`) and it names the model folder (`<artifacts_dir>/<name>/`), so a name that means something to them — their database, product, team, or environment — beats a generic default. **On the password-page path this card comes after the connection fields (0a.4c)**, because the fields card asks for the database's own name and a separate "what should I call this database?" before it reads as the same question twice. Here the name is for the *connection*, and the database name the person just gave is the natural answer. **AskUserQuestion**, header `Name`: > *"What should agami call this connection? It's how you'll pick it when you connect more than one. Type your own in Other."* Options: `<database> (Recommended)`, the database name from 0a.4c made valid (lowercased, any other character turned into `-`, trimmed to 32), and `<database>-<where>`, with `<where>` = `local` for `localhost`/`127.0.0.1` or the first label of the host otherwise (`<database>-<account>` on Snowflake, `<project>` alone on BigQuery, the file's stem for SQLite and DuckDB). Leave out an option that would equal the other or fail the rules below. **On the file path** (no fields card), ask it here, before the file: *"What should agami call this database? It's how you'll pick it when you connect more than one, so your database or product name works well. Type it in Other."* with `prod`, `staging` and `analytics` as examples. **Don't present a `main` default that nudges them past the choice.** Bind `$PROFILE_NAME` to their answer (the Other text, or a picked option). Validate: lowercase letters/digits/dashes/underscores, 1–32 chars; **and not already a `[section]` in `<artifacts_dir>/local/credentials`** (a profile name is a unique key — reusing one would clash). If it fails either rule, show the reason and re-ask. (The 0a.10 promote helper enforces the uniqueness backstop too — it returns `COLLISION` rather than overwrite — but catch it here so the user isn't surprised later. On the password-page path the helper checks again, and also refuses a name the OS store already holds a password under.) Say "database", not "profile", to the person. ### 0a.4c — The connection fields as one card (macOS and Windows) **Only on the password-page path** (see the top of Phase 0a). Linux, and Databricks on any system, use the file in 0a.4 instead. One AskUserQuestion, header per question, **one question per non-secret field** (at most 4). **The password is never on this card**: it goes on the page in 0a.4k. Every question takes the real value in "Other"; the options are the obvious defaults and common values, so the person presses one when it fits and types otherwise. No option is marked Recommended (these are facts about their setup). Put a line in the first question's prompt: *"Type yours in Other when the options don't fit, for example `your-cluster.example.com` (never a password or a URL that holds one: the password goes on a separate page)."* | `$DB_TYPE` | questions (header: options) | spec `fields` keys | `auth` | |---|---|---|---| | postgres / redshift | `Host`: `localhost` (this computer), `127.0.0.1` · `Port`: `5432` (PostgreSQL default), `5439` (Amazon Redshift), `6543` (Supabase pooler) · `Database`: `postgres` (the default database), `analytics` · `User`: `readonly` (a read-only user, the safest), `postgres` | `host`, `port`, `database`, `user` | `password` | | mysql | `Host`: as above · `Port`: `3306` (MySQL default), `3307` · `Database`: `analytics`, `app` · `User`: `readonly`, `root` | same | `password` | | sqlserver | `Host`: as above · `Port`: `1433` (default), `1434` · `Database`: `master`, `analytics` · `User`: `readonly`, `sa` | same | `password` | | oracle | `Host`: as above · `Port`: `1521` (default), `1522` · `Service`: `ORCLPDB1`, `XEPDB1` · `User`: `readonly`, `system` | `host`, `port`, `service_name`, `user` | `password` | | snowflake | `Account`: `acme-xy12345` (org-account form), `xy12345.us-east-1` (locator form) · `User`: `readonly`, `analyst` · `Warehouse`: `COMPUTE_WH` (Snowflake's default), `ANALYTICS_WH` · `Sign-in`: `Password` (typed on a one-time page), `Browser sign-in (SSO)` (your company's sign-in, no password) | `account`, `user`, `warehouse` (+ `authenticator = externalbrowser` for SSO) | `password`, or `sso` for browser sign-in | | trino | `Host`: as above · `Port`: `8080` (HTTP default), `443` (HTTPS) · `User`: `readonly`, `admin` · `Catalog`: `hive`, `iceberg`; then a second card, `Password`: `No password`, `Password (HTTPS)` | `host`, `port`, `user`, `catalog` | `sso` for no password, else `password` | | bigquery | `Project`: `acme-analytics`, `acme-prod` · `Sign-in`: `Google sign-in on this computer` (gcloud application-default login), `A service-account key file` (its path in Other; the path, never the file's contents) | `project` (+ `service_account_path`) | `sso` | | sqlite / duckdb | `File`: the absolute path in Other; options `~/data/app.db`, `~/data/app.duckdb` (examples) | `path` | `sso` | Snowflake's database, schema and role, and Postgres' `sslmode`, are optional: ask them on a second card only when the person mentions them or the connection fails without them. Read the answers into the spec's `fields`, as strings. Expand `~` to an absolute path. **When an answer can't be used, say why in one line and ask that question again** (an empty answer; a port that isn't a number; an example value such as `acme-xy12345` or one containing `example` that is plainly not theirs; a value with `%`, or starting with `#` or `;`, which the credentials file can't hold). A host that is a full URL with a password in it: don't use or repeat it (HARD RULE 2), and ask for the host alone. Then run 0a.5 → 0a.8 (interpreter, agami-core, the artifacts folder, `.config`), and go to 0a.4k. ### 0a.4k — the password page (macOS and Windows) The password goes from the person's browser straight into the OS credential store (Keychain on macOS, Credential Manager on Windows). It is never in the chat, on a command line, in a file, or in your context: you never see it, so never ask for it, and if it is typed into the chat anyway, follow HARD RULE 2. **1. Write the spec** with the Write tool to `<artifacts_dir>/local/tmp/agami-connect-spec.json` (non-secret fields only; there is no password key): ```json {"profile": "<$PROFILE_NAME>", "db_type": "<$DB_TYPE>", "fields": {"host": "<host>", "port": "<port>", "database": "<database>", "user": "<user>"}} ``` For a connection with no secret to type (Snowflake browser sign-in, BigQuery, Trino with no password, SQLite, DuckDB) add `"auth": "sso"`. **The `sso` path has no link and no page:** the helper writes the section, tests the connection, and prints only its final line, so skip step 3 and read that line in step 4. Its wait is longer than the password path's (step 2). **2. Start the helper in the background.** Call Bash with `run_in_background: true`: ```bash bash "${CLAUDE_PLUGIN_ROOT}/scripts/py" connect_helper.py --spec "<artifacts_dir>/local/tmp/agami-connect-spec.json" ``` Stdout is JSON lines and nothing else. **Wait for the helper's first line with the Monitor tool**: the Bash result names the task and its output file, so use the Monitor tool to watch the helper's output until its first line, or the task's exit (an until-loop on that output file that stops on the first JSON line, or when the task has exited). Never run a foreground `sleep`: the Desktop Code tab blocks it. As a fallback where Monitor isn't available, re-read the output file at spaced intervals, each read its own tool call, never a tight loop. Stop waiting when one of these happens: - **The first line has a `status`**: it is the final line. Every check that runs before the page (`missing_driver`, `name_taken`, `no_store`, `stale_install`, and the other refusals), and the whole `sso` path, prints that one line and exits. Skip step 3 and go to step 4 with it. - **The first line has a `url`** (`{"url": "http://127.0.0.1:<port>/<token>/", "expires_in": 300, "pid": <n>}`): the page is listening, usually within a second. Go to step 3. - **The background task has exited with no line, or, on the password path, about 15 seconds pass with no line**: the helper failed before it could print (an import error, say, which goes to stderr only). Stop the task if it is still running (below), show the last stderr line in one sentence, and ask a card, header `Next step`: `Try again` (step 2 again) / `Use a file instead (manual)` (0a.4). **With `"auth": "sso"` (`auth: sso`) there is no 15-second limit.** The helper tests the connection before it prints anything, and that test can open a browser sign-in (Snowflake's SSO, say) that waits for the person. So tell the person once, when you start the helper, that a browser sign-in may open and that you are waiting for it to finish, then wait until the helper exits, up to 5 minutes, with the same Monitor watch. Don't repeat the line while waiting. Past 5 minutes with no exit, stop the task (below) and ask the `Next step` card above. Don't run the helper in the foreground: it would hold the turn until the page is submitted, and the link would never reach the person. Where background commands aren't available, use the file path (0a.4) instead. **3. Post the link** as a clickable markdown link, with this sentence and how long it lasts: > [Enter your password](http://127.0.0.1:<port>/<token>/). Enter the password on this page; it goes to your keychain, not the chat. The link expires after 5 minutes. (On Windows say "Windows Credential Manager" in place of "your keychain".) **Then a card, so the link isn't missed** (a line of chat is easy to scroll past; a live run showed exactly that). AskUserQuestion, one question, header `Password`: *"Enter the password on the page at http://127.0.0.1:<port>/<token>/ (open for 5 minutes), then come back here."* Options: **I've saved it** / **New link** / **Use a file instead (manual)**. - **I've saved it** → read the helper's output: a final line is there → step 4. None yet → say the page hasn't been submitted, and ask the card again. - **New link** → stop the running helper (below) and start step 2 again with the same spec. - **Use a file instead (manual)** → stop the helper, then 0a.4. The helper exits when the page is submitted or the 5 minutes pass, and that exit also brings you back if the card is still open: go to step 4 and don't ask the card again. Never wait silently: if the person writes before the helper is done, answer, and remind them the link is still open. If they want to stop, stop the background task with TaskStop and its task id (the helper then takes back whatever it stored), and show the database-type card again. Where TaskStop isn't available, on macOS and Linux `kill <pid>` with the `pid` from the helper's first line stops it the same way (it asks for permission; `kill` sends SIGTERM, and the helper takes back whatever it stored). On Windows, and without a `pid` (the `sso` path prints none), the helper is left to stop by itself when its 5 minutes are up: say so, and wait for its exit before starting it again. **4. Read the final line** of the output when the helper exits, and act on it. The exit is what you wait for after the link is posted: the Monitor tool watching the task until it exits (or, as the fallback, spaced re-reads of the output file), never a foreground `sleep`; the background task's exit notice also brings you back. Exit code is 0 for every outcome; `status` (and a refusal's `reason`) says what happened, and `detail` is the one line to show the person. Each outcome gets one sentence plus the next card: | final line | say | next | |---|---|---| | `connected` | *"Connected to `<name>`. The password is in your keychain."* (or the Windows store) | Run `setup_pgauth.py --all` (as in 0a.10) and continue to Phase 1. | | `connect_failed` | `detail` (why it failed). Nothing was kept: the helper removed the section and the stored password. | Card `Next step`: `Try again` (the same fields, a new link; the person may have mistyped the password) / `Change the connection details` (0a.4c again) / `Use a file instead (manual)` (0a.4). | | `expired` | *"The link expired before the page was submitted; nothing was saved."* | Card `Next step`: `New link` (step 2 again, same spec) / `Use a file instead (manual)`. | | `missing_driver` | `detail`, which names `package`. | Card `Driver`: `Install <package>` (with the real package names) / `Not now`. On the press, install into the interpreter `scripts/py` uses: `bash "${CLAUDE_PLUGIN_ROOT}/scripts/py" -m pip install --user <package>` (unquoted: `package` can hold two names, `duckdb pytz`), then step 2 again. If pip fails, show its last line and offer `Try again` / `Not now`. `Not now`: stop with *"Connect again when you're ready to install it."* | | `refused`, `no_store` | `detail` (agami's keyring library isn't set up for the OS store yet). | Card `Secure store`: `Set up secure storage` / `Use a file instead (manual)`. The first runs `bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install` (it adds `keyring` on macOS and Windows), then step 2 again. | | `refused`, `stale_install` | `detail` (the agami-core this Python has is too old for the store). | Card `Update`: `Update agami` (runs `bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install`, then step 2 again) / `Use a file instead (manual)`. | | `refused`, `name_taken` or `saved_password_exists` | `detail` (the name is in use here, or the OS store already holds a password under it). | The name card (0a.3) again, then a new spec and step 2. | | `refused`, `bad_name` | `detail`. | The name card (0a.3) again. | | `refused`, `bad_field` | `detail` (a field the credentials file can't hold). | The connection fields card (0a.4c) again. | | `refused`, `bad_spec` | Nothing to the person: the spec file you wrote is unreadable. | Rewrite it (step 1) and run step 2 again, once. A second `bad_spec`: say connecting failed and offer `Use a file instead (manual)`. | | `refused`, `unreadable_credentials` or `linked_credentials` | `detail` (the credentials file under `<artifacts_dir>/local/` can't be parsed, or it or `local/` is a link). | Card `Next step`: `I've fixed it` (step 2 again) / `Stop`. Never open or print the file: it can hold passwords. | | `refused`, `unsupported_os` | `detail`. | The file path: 0a.4, then 0a.9. | | `refused`, `not_replaceable` | `detail` (`--replace` was run for a profile that doesn't exist or doesn't keep its password in the OS store). | Connect it as a new profile: the name card (0a.3), then step 2 without `--replace`. | | `refused`, `store_error` or `write_failed` | `detail` (the store or the credentials file refused the write; nothing was kept). | Card `Next step`: `Try again` (step 2) / `Use a file instead (manual)`. | `Use a file instead (manual)` always means 0a.4 → 0a.9 → 0a.10, the same as Linux. A line that is not one of these, or no final line at all: show the last line of output and offer `Try again` / `Use a file instead (manual)`. Delete the spec file once the helper has exited. On `connected` (the connection test passed), mark the step done and refresh the task list ([shared/task-list.md](../../shared/task-list.md)): ```bash bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" steps "<root>" --mark connect=done ``` ### 0a.4 — Write `<artifacts_dir>/local/credentials.example` **The file path:** Linux and any system without a secure store, Databricks on every system, and whoever picks `Use a file instead (manual)` in 0a.4k. The person types the password into the file themselves, so it never passes through the chat. Use the **Write tool**. Shared header first, then the `$DB_TYPE` body with `[$PROFILE_NAME]` as the section. **Header:** ```ini # <artifacts_dir>/local/credentials.example # Fill in your values below and save, then press "I've filled it in" in the chat. # agami moves this file to <artifacts_dir>/local/credentials and chmod-600s it for you — no # manual save or chmod needed. (Don't rename it yourself.) # agami only runs read-only SELECT queries, so a read-only database user is all it needs # (and the safest thing to connect). Copy-paste GRANT SQL for your database: # plugins/agami/shared/readonly-grants.md — or ask agami for "the read-only grant". # Format reference: plugins/agami/shared/credentials-format.md # Switch profiles with AGAMI_PROFILE=<name>. ``` Bodies — `postgres`, `redshift`, `snowflake`, `mysql`, `bigquery`, `sqlite` are unchanged from [`shared/credentials-format.md`](../../shared/credentials-format.md) (URL-form first for Postgres/MySQL/Redshift; account fields for Snowflake; `project`+`service_account_path` for BigQuery; `path` for SQLite). The new dialects: ```ini # SQL Server / Azure SQL. [$PROFILE_NAME] type = sqlserver host = your-server.database.windows.net port = 1433 database = your-database user = your-username password = your-password ``` ```ini # Oracle. [$PROFILE_NAME] type = oracle host = your-host.example.com port = 1521 service_name = ORCLPDB1 user = your-username password = your-password # OR a full DSN: dsn = host:1521/ORCLPDB1 ``` ```ini # Databricks SQL warehouse. [$PROFILE_NAME] type = databricks host = your-workspace.cloud.databricks.com http_path = /sql/1.0/warehouses/abc123 token = dapiXXXXXXXXXXXX # catalog = main # optional Unity Catalog ``` ```ini # Trino / Presto. [$PROFILE_NAME] type = trino host = your-coordinator.example.com port = 8080 user = your-username catalog = your_catalog schema = your_schema # password = ... # uncomment for HTTPS + basic auth ``` ```ini # DuckDB (local file or in-memory). [$PROFILE_NAME] type = duckdb path = /absolute/path/to/your.duckdb ``` Always finish with the additional-profiles hint (one commented block): ```ini # Add more profiles by appending another [section]. Switch with AGAMI_PROFILE=<name>. # [staging] # type = postgres # url = postgresql://readonly:pass@staging-db.example.com:5432/mydb ``` For BigQuery / Databricks / any key-or-token file: remind the user to `chmod 600` it. ### 0a.5 — Resolve the agami interpreter + detect tools **`<python3>` = `data.interpreter.python3`, written out in full, from the Phase-0 `connect_resolve.py` call** — the ONE Python agami uses for the model *and* DB connections (introspection always runs `python -m execute_sql` under it on *every* tier, so the DB driver must live in it). It's already the **scored** pick — the candidate that has `pydantic`+`sqlglot`+`pyyaml` AND the `$DB_TYPE` driver — so there's no guessing and the user sets nothing. **Re-run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/py" connect_resolve.py --db-type <db_type>` now** that the DB type is known, so the interpreter is scored against the right driver and native tools are refreshed. It records as `tool_paths.python3` in 0a.7. (`AGAMI_PYTHON` is honored as a first-priority override but is never required.) Native CLIs (optional fast path for *queries* — introspection doesn't use them) are in `data.tools` (`psql`/`mysql`/`snowsql`/`sqlite3`/`duckdb`/`bq`, `null` if absent), detected with `which` only. **Forbidden** elsewhere: `pgrep`/`ps`/`lsof`/`find /`/`ls /Applications`/port scans. **If `data.interpreter.has_driver` is `false`** the `$DB_TYPE` driver isn't in `<python3>` yet — confirm via AskUserQuestion, then `"<python3>" -m pip install --user <package>` from the table, where `<python3>` is `data.interpreter.python3` written out in full (probe was already done in `<python3>` by `connect_resolve.py`): | `$DB_TYPE` | probe (`"<python3>" -c '…'`) | pip package | |---|---|---| | postgres / redshift | `import psycopg2` | `psycopg2-binary` | | mysql | `import pymysql` | `pymysql` | | snowflake | `import snowflake.connector` | `snowflake-connector-python` | | bigquery | `import google.cloud.bigquery` | `google-cloud-bigquery` | | sqlserver | `import pymssql` | `pymssql` | | oracle | `import oracledb` | `oracledb` | | databricks | `from databricks import sql` | `databricks-sql-connector` | | trino | `import trino` | `trino` | | duckdb | `import duckdb, pytz` | `duckdb pytz` | | sqlite | stdlib — always present | — | > **duckdb needs `pytz`** to materialize `TIMESTAMP WITH TIME ZONE` values into Python — without it a query that selects a timestamptz column fails at runtime (`Required module 'pytz' failed to import`), so it's part of the driver install, not optional. If the driver is missing, **confirm via AskUserQuestion**, then `"<python3>" -m pip install --user <package>` (plain `pip install` fallback). Same "never install silently" convention as the model deps (0a.5b). Do this for `<python3>` so `sm introspect` connects on the first try. ### 0a.5b — Ensure the semantic-model dependencies **This runs first, right after 0a.0**: saving the folder (0a.6), setting it up (0a.1) and writing `.config` (0a.7) need agami's library, and none of them installs it (each stops with exit code 12 and the install step instead), so the person agrees to the install before anything is set up. The model (introspection, validation, traversal, curation — everything the `sm` wrapper drives) needs **`pydantic` + `sqlglot` + `pyyaml`** in the interpreter agami uses. The resolve step already checked the interpreter it picked: `data.interpreter.core_ready` in its output (preflight step 1) says whether agami's library is ready in it (the deps, the agami-core package itself and this plugin's version), so no command is needed here. Decide on `core_ready`, never on `has_model_deps` alone: the deps can be there with no agami-core, and then every setup call stops with exit code 12. If it is ready, continue. If missing, **confirm via AskUserQuestion before installing** (same convention as the DB-driver install above — agami never installs silently): > agami needs the **agami-core** package (which pulls `pydantic`, `sqlglot`, `pyyaml`) to build and read the semantic model. Install it now? (one-time, user-site — `pip install --user`) On **Yes**: `bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" install` — the `sm` launcher is the single place that installs the agami-core library into the resolved interpreter (editable from a dev checkout, else the published package via PyPI or pinned git — so it works in a marketplace install with no `packages/` dir), and everything (`python -m execute_sql` / `python -m semantic_model.cli` / `sm`) then resolves it. On **No**: stop with *"Can't build the model without it — re-run when you're ready to install."* — don't proceed to introspect. (The `sm` wrapper also self-installs these on first use as a safety net, but doing it here makes it explicit, confirmed, and at a predictable moment rather than mid-introspection.) ### 0a.6 — Ask for `<artifacts_dir>` (first run only) **This runs before 0a.1**, because 0a.1 and 0a.7 act only on the folder agami has saved. **The folder is chosen once, on the very first onboarding, and reused for every profile thereafter.** Whether it is already set is in the resolve step's output (preflight step 1): when `data.artifacts_dir_source` is `env` (`AGAMI_ARTIFACTS_DIR`) or `pointer` (the saved pointer), **or** `data.config.present` is true, **skip this question entirely** — reuse `data.artifacts_dir` and continue to 0a.1. Never read or list the pointer file yourself. Only a brand-new install (`artifacts_dir_source` is `default` and no `.config`) reaches the question below. This guarantees a second/third database lands as a sibling inside the same folder rather than re-prompting (and risking a fragmented, multi-folder setup). The options follow the operating system the session's environment names (as at the top of Phase 0a). Then **AskUserQuestion** with the two defaults for that OS as named options (Recommended first). The auto-provided **Other** lets the user type any absolute path — so this both gives sensible options *and* allows a full custom path: > Where should agami save your semantic model, examples, and preferences? This is the **parent** for ALL profiles — each lands in `<artifacts_dir>/<profile>/`. It's non-secret (no credentials) — point it inside a git repo to share the tuned model with your team. Credentials stay in `<artifacts_dir>/local/` regardless. | OS | Option 1 — Recommended | Option 2 | |---|---|---| | macOS | `~/agami-artifacts` | `~/Documents/agami-artifacts` | | Linux | `~/agami-artifacts` | `~/Documents/agami-artifacts` | | Windows | `%USERPROFILE%\agami-artifacts` | `%USERPROFILE%\Documents\agami-artifacts` | (For Other, suggest a team repo path as the example, e.g. `~/code/acme-data/agami`.) Expand `~` / `%USERPROFILE%` to an absolute path, then save the choice, whichever option it is, with one call (it checks the folder is absolute, not a file and not inside `<artifacts_dir>/local/`, and writes the pointer at `<home>/.config/agami/path` so future sessions find it; never write the pointer yourself): ```bash bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" choose-folder "<artifacts_dir>" ``` An `error` is said back and the same card asked again. Then 0a.1; 0a.7 records the folder in `.config`. ### 0a.7 — Write `<artifacts_dir>/local/.config` One call, which checks each value and keeps every other key in the file (written 0600): ```bash bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" set-config "<artifacts_dir>" --tier <tier> --active-profile <profile> --python3 "<python3>" --tool <tool>="<tool_path>" ``` `<tier>` is `cli`, `duckdb` or `python`; `--tool` names the native query tool the tier uses (`psql`, `mysql`, `snowsql`, `sqlite3` or `duckdb`) with its absolute path, left out for the `python` tier. `python3` MUST be the `<python3>` resolved in 0a.5 (the interpreter that has both the model deps and the DB driver) — `sm` and the introspection engine read it from here, so recording the wrong one reintroduces the interpreter mismatch. Never write `.config` with the Write tool. The database's folder is known from here, `<root>` = `<artifacts_dir>/<profile>`: mark the step started and refresh the task list ([shared/task-list.md](../../shared/task-list.md)): ```bash bash "${CLAUDE_PLUGIN_ROOT}/scripts/sm" steps "<root>" --mark connect=in_progress ``` ### 0a.8 — Seed `<artifacts_dir>/USER_MEMORY.md` if missing Write the default seed (per [`shared/user-memory-format.md`](../../shared/user-memory-format.md)) with the Write tool, which makes the folder; the file comes out readable by others under the usual umask, as this non-secret file should, so it needs no `chmod`. Don't overwrite. Migrate a v1.1 `<artifacts_dir>/local/USER_MEMORY.md` if present. **Then write what 0a.0 held** (the folder and the interpreter exist now): the company (1.4 A's two writes) and, when it was given, the personal-data setting (`sm set-personal-data`). The fiscal year waits for 1.7. ### 0a.9 — Hand-off, then a reply that waits for the file Show the summary; it ends the turn with the reply line below (a summary before a card in the same message does not reach the person, [long-text.md](../../shared/long-text.md)). ``` ✓ <artifacts_dir>/local/ ready (chmod 700) ✓ Credentials template → <artifacts_dir>/local/credentials.example ✓ Tool detected: <tool> (<tier>) ✓ Artifacts dir: <resolved path> Open <artifacts_dir>/local/credentials.example, fill in your connection details and save it (keep the filename as-is — don't rename it). I'll secure the file and run the full introspect → enrich → seed flow. Tip: agami only runs read-only queries, so a read-only database user is all it needs (and safest). Want the exact GRANT SQL for your database? Just ask. ``` The reply line: *Reply "I've filled it in" once the file is saved, or "show me the file again".* Handle the reply as the choices below; words that mean one of them count as it: | label | description | then | |---|---|---| | `I've filled it in` | Secure the file and connect | 0a.10 | | `Show me the file again` | Where the file is and what to fill in | Print the path and the field names of the `[$PROFILE_NAME]` section from the template you wrote (from your own copy, never by reading the file: once filled in it holds the password), then the reply line again. | The reply is the wait: don't continue to Phase 1 until `I've filled it in` is said (or, in a later session, until the person comes back with any data question and preflight returns `promote`). Show the read-only **Tip** line only for dialects with a user/role concept (`postgres`, `redshift`, `mysql`, `snowflake`, `sqlserver`, `oracle`, `databricks`, `trino`); **omit** it for `sqlite` / `duckdb` (file-based, no user) and when BigQuery auth is ADC. If the user asks for the grant, read [`shared/readonly-grants.md`](../../shared/readonly-grants.md), pick the `$DB_TYPE` block, and fill in whatever `<…>` placeholders it uses (e.g. `<db>` / `<schema>` / `<warehouse>` / `<catalog>` / `<project>` / `<dataset>`) from the values they entered. ### 0a.10 — On re-entr
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.