dataspring-cli 0.4.1__py3-none-any.whl → 0.4.2__py3-none-any.whl

cli/_skills/dataspring-author/SKILL.md

@@ -206,6 +206,18 @@ version produced each issue. Edit the board and the next issue follows.
 and is what stops later history columns moving. Rendering and checking
 prose is the consumer's job and is covered in `dataspring-consume`.
 
+## 8.2 Iterating on a dbt model (managed tenants)
+
+A model change does not need a load. The loop is `datacore_edit` (kind
+`model`), `datacore_run` `check`, `deploy`, then `build`: a run that loads
+no resource and runs `dbt build` of the deployed project on the raw tables
+already there, with an optional `select` (default: the named pipeline's
+`then.dbt_select`, or every model). `deploy` with `then_build: true` (and
+`build_select`) queues it in the same call when the deploy changed a file
+under `models/`. Do not use `run` to see a model change: it reloads every
+resource of the pipeline first. CLI: `dataspring datacore build --select
+"marts.finance+" --wait`.
+
 ## 9. Parameter reference
 
 <!-- dispatch-params: semantic_model_edit metric_edit board_edit briefing_edit import_manifest business_context_edit warehouse_edit datacore_edit datacore_run -->
@@ -461,6 +473,8 @@ MCP tool `datacore_run`; `POST /api/dispatch/datacore_run`. The datacore's check
 |---|---|---|---|
 | `snapshot` | string | no | Omit to promote the current draft (needs a green check bound to it). A previously deployed snapshot id rolls back to it |
 | `note` | string | no | Why, recorded on the learned trail |
+| `then_build` | boolean | no, default `False` | When the deploy changed any file under models/, also queue a models-only build (the `build` action) of the newly deployed snapshot on the raw tables already loaded; build_select narrows it. Without it, a deploy that changed models answers with the command that does it |
+| `build_select` | string | no | With then_build: the dbt selector to rebuild (default: every model, `fqn:*`) |
 
 **`run`** — 
 
@@ -471,6 +485,13 @@ MCP tool `datacore_run`; `POST /api/dispatch/datacore_run`. The datacore's check
 | `cursor` | RunCursorParams | no | {from: <value>}: a cursor to re-pull from |
 | `backfill_chunk` | string | no | Chunk size for a windowed run: 7d, 2w or 1M (calendar months, the default) |
 
+**`build`** — Rebuild the deployed dbt models on the raw tables already loaded: no resource is loaded.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `pipeline` | string | no | A deployed pipeline whose `then` block names what to build (its dbt_select, dbt_exclude and tests). Omit to build every model of the deployed project |
+| `select` | string | no | A dbt selector (`dbt build --select`), e.g. `marts.finance+` or `+fct_postings`; replaces the pipeline's dbt_select and dbt_exclude. Default: the pipeline's then.dbt_select, or every model (`fqn:*`) when no pipeline is named |
+
 **`reset`** — 
 
 | Parameter | Type | Required | Description |

cli/_skills/dataspring-consume/SKILL.md

@@ -656,7 +656,7 @@ MCP tool `query_metrics`; `POST /api/dispatch/query_metrics`. Fetch metric data
 | `order_by` | string | no | Column to sort by, append ' desc' for descending (e.g., 'total_revenue desc') |
 | `where` | list of string | no | Row filters in MetricFlow's constraint syntax, one string each, e.g. "{{ Dimension('customer__segment') }} NOT IN ('Direct')". Use qualified names from dataspring://dimensions - an unresolvable name comes back as an error whose suggestion names the qualified form. `where` decides WHICH ROWS the numbers cover; `dimensions` breaks the numbers OUT by a column; send both for a breakdown of a filtered slice. A `where` on a dimension also overrides the user's standing filter on that same dimension for this call. |
 | `warehouse` | string | no | Which of the org's warehouses to run against - an id from dataspring://warehouses ('managed', 'external', ...). Omit for the active one. During a migration ask both and compare. |
-| `compare_to` | one of `previous_period`, `same_period_last_year` | no | Compare the window against the one before it (previous_period, stepped back by whole calendar periods when the window is whole ones) or the same window a year earlier (same_period_last_year). The deltas come back BESIDE the values - each metric column gains <metric>__previous, <metric>__delta and <metric>__delta_pct - so there is no second result set to line up and no arithmetic to do. `comparison_period` says which window they were measured against. |
+| `compare_to` | one of `previous_period`, `same_period_last_year` | no | Compare the window against the one before it (previous_period, stepped back by whole calendar periods when the window is whole ones, and by as many periods as it touches, keeping its position, when it cuts a period short: a year to date compares with the same days a year earlier) or the same window a year earlier (same_period_last_year). The deltas come back BESIDE the values - each metric column gains <metric>__previous, <metric>__delta and <metric>__delta_pct - so there is no second result set to line up and no arithmetic to do. `comparison_period` says which window they were measured against. |
 | `suggest_visualization` | boolean | no, default `False` | Also return a suggested visualization type for the result. |
 | `format` | one of `json`, `csv` | no, default `json` | 'json' (default) answers rows in `data`; 'csv' answers the same result as one CSV document in `content` (header row first) for a file or a spreadsheet, with `columns` and `row_count` alongside. |
 
@@ -672,7 +672,7 @@ MCP tool `board_fetch`; `POST /api/dispatch/board_fetch`. Run every row of a boa
 | `grain` | one of `day`, `week`, `month`, `quarter`, `year` | no | Bucket grain for each row's history. Defaults to the period's own grain. |
 | `start_date` | string | no | Start date in YYYY-MM-DD format, instead of a named period |
 | `end_date` | string | no | End date in YYYY-MM-DD format, instead of a named period |
-| `compare_to` | one of `previous_period`, `same_period_last_year` | no | Compare the window against the one before it (previous_period, stepped back by whole calendar periods when the window is whole ones) or the same window a year earlier (same_period_last_year). The deltas come back BESIDE the values - each metric column gains <metric>__previous, <metric>__delta and <metric>__delta_pct - so there is no second result set to line up and no arithmetic to do. `comparison_period` says which window they were measured against. |
+| `compare_to` | one of `previous_period`, `same_period_last_year` | no | Compare the window against the one before it (previous_period, stepped back by whole calendar periods when the window is whole ones, and by as many periods as it touches, keeping its position, when it cuts a period short: a year to date compares with the same days a year earlier) or the same window a year earlier (same_period_last_year). The deltas come back BESIDE the values - each metric column gains <metric>__previous, <metric>__delta and <metric>__delta_pct - so there is no second result set to line up and no arithmetic to do. `comparison_period` says which window they were measured against. |
 | `detail` | one of `salient`, `full` | no, default `salient` | 'salient' (default) answers EVERY row compactly - value, delta, and whether it is notable - and adds the full detail (history, sparkline, receipt, freshness, which rule fired) only for the rows that are notable plus any named in `rows`. 'full' answers everything for every row, for an export or a spreadsheet. |
 | `rows` | list of string | no | Row ids to return in full detail whether or not they are notable. |
 | `history` | integer | no, default `13` | How many periods of history to fetch per row, for the sparkline and the volatility measure. |
@@ -703,7 +703,7 @@ MCP tool `run_sql`; `POST /api/dispatch/run_sql`. Run ONE read-only SQL statemen
 
 | Parameter | Type | Required | Description |
 |---|---|---|---|
-| `sql` | string | yes | One SQL statement (BigQuery Standard SQL on a managed warehouse). Name tables as <org>_marts.<table>, <org>_core.<table> or <org>_staging.<table>; the identity it runs as can read those and nothing else, so a write or a reach outside them is refused by the warehouse. |
+| `sql` | string | yes | One SQL statement (BigQuery Standard SQL on a managed warehouse). Name tables as <org>_marts.<table>, <org>_core.<table> or <org>_staging.<table>, <org> being the organization id with every hyphen as an underscore (acme-dk is acme_dk_marts); the identity it runs as can read those and nothing else, so a write or a reach outside them is refused by the warehouse. |
 | `warehouse` | string | no | One of the org's warehouses (see dataspring://warehouses); omit for the active one. |
 | `max_rows` | integer | no, default `1000` | Rows to return at most (default 1000, cap 10000). Aggregate in SQL rather than paging. |
 | `format` | one of `json`, `csv`, `markdown` | no, default `json` | 'json' answers rows in `data`; 'csv' or 'markdown' answer one document in `content`. |

cli/auth.py

@@ -4,15 +4,26 @@
 backend/routes_device.py): the CLI shows a code and a URL, a person signed in
 to DataSpring in any browser (this machine needs none) approves it, and the
 CLI collects an ordinary ``ds_`` API key labelled ``CLI on <hostname>`` (one
-per org with ``--all-orgs``, the default).
+per org with ``--all-orgs``).
 
 Credentials live in ``~/.dataspring/credentials.json`` (mode 0600): a profile
-per org and which one is current. ``dataspring auth use <org>`` switches
-profile; a key belongs to its org, so that is the only switching there is
-(hub D-96: no server-side switch). ``--key`` stores a key you already have,
-for CI, and the ``DATASPRING_API_KEY`` environment variable always wins over
-anything stored. ``dataspring auth logout`` revokes the stored keys on the
-server, then forgets them.
+(a key) per org. Nothing machine-wide says which one a command uses (hub
+D-99: ``auth use`` went, because two agents on one machine moved each other
+between orgs); every command resolves its org afresh, in this order
+(:meth:`CLIAuthManager.resolve`):
+
+1. ``--org`` on the command;
+2. ``DATASPRING_ORG``, then ``FORSPRING_ORG``;
+3. ``.forspring.json`` (``{"org": "noon"}``) in this directory or a parent;
+4. the key's own org, when ``DATASPRING_API_KEY`` is set (a key belongs to
+   one org);
+5. the only stored profile;
+
+else it refuses with ``org_required``, the stored orgs and the three ways to
+name one, and never prompts. ``DATASPRING_API_KEY`` always wins over the
+stored keys: with it, a named org that is not the key's is ``org_mismatch``.
+``--key`` stores a key you already have, for CI. ``dataspring auth logout``
+revokes the stored keys on the server, then forgets them.
 
 Who the person is and which org a key is for are the server's answer to
 ``/api/me``; nothing here opens Firestore.
@@ -31,8 +42,30 @@ from pathlib import Path
 
 import httpx
 
+from cli.refusals import EN, NAME_AN_ORG, Refusal, classify, from_body
+
 ENV_KEY = "DATASPRING_API_KEY"
 
+#: Step 2 of the org order: the product's own variable, then the suite's.
+ORG_ENV_VARS = ("DATASPRING_ORG", "FORSPRING_ORG")
+
+#: Step 3: the per-project file, committed next to the code (``{"org": "noon"}``).
+PROJECT_FILE = ".forspring.json"
+
+#: ``org_from`` for steps 4 and 5.
+FROM_KEY = ENV_KEY
+FROM_ONLY_PROFILE = "only_profile"
+
+#: Step 1, ``--org``: set by the root command (``cli.main``) for this
+#: invocation; ``None`` when not given.
+_org_flag: str | None = None
+
+
+def set_org_flag(org: str | None) -> None:
+    """``--org`` for this invocation (``cli.main``'s root callback)."""
+    global _org_flag
+    _org_flag = (org or "").strip() or None
+
 
 def _host() -> str:
     """The backend's root (https://dataspring.app; locally http://localhost:8000)."""
@@ -67,12 +100,100 @@ class UserContext:
 
 
 class AuthenticationError(Exception):
-    """Raised when authentication fails or user is not logged in."""
-    pass
+    """Raised when authentication fails or user is not logged in.
+
+    ``exit_code`` is what the CLI ends with (suite standards §6): 1, a plain
+    failure, unless a subclass says otherwise.
+    """
+
+    exit_code = 1
+
+
+class Refused(AuthenticationError):
+    """A D-99 refusal (``cli.refusals``): not signed in, no org named, a key
+    for another org, or the server's own refusal of the key."""
+
+    def __init__(self, reason: str, note: str, fix: str | None = None):
+        self.refusal = Refusal(reason, note, fix)
+        super().__init__(self.refusal.message)
+
+    @property
+    def reason(self) -> str:
+        return self.refusal.reason
+
+    @property
+    def exit_code(self) -> int:  # type: ignore[override]
+        return self.refusal.exit_code
+
+
+class ProjectFileError(AuthenticationError):
+    """A ``.forspring.json`` that names no org: invalid input (2)."""
+
+    exit_code = 2
+
+
+@dataclass(frozen=True)
+class ResolvedOrg:
+    """Which key a command sends, for which org, and where the org came from.
+
+    ``org_id`` is ``None`` only for ``DATASPRING_API_KEY`` with no org named
+    and no stored profile holding that key: the key knows its org, and the
+    server says which (``GET /api/me``). ``org_from`` is ``--org``,
+    ``DATASPRING_ORG``, ``FORSPRING_ORG``, ``.forspring.json``,
+    ``DATASPRING_API_KEY`` or ``only_profile``; ``org_file`` is the file
+    step 3 read.
+    """
+
+    key: str
+    org_id: str | None
+    org_from: str
+    org_file: str | None = None
+
+
+def _not_signed_in(detail: str = "Not logged in.") -> Refused:
+    return Refused("not_signed_in", detail, "Run 'dataspring auth login' (or set DATASPRING_API_KEY).")
+
+
+def find_project_file(start: Path | None = None) -> Path | None:
+    """The nearest ``.forspring.json`` in ``start`` (default: the working
+    directory) or a parent."""
+    here = (start or Path.cwd()).resolve()
+    for directory in (here, *here.parents):
+        candidate = directory / PROJECT_FILE
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def read_project_org(path: Path) -> str:
+    """The ``org`` a ``.forspring.json`` names; a file that names none is an error."""
+    shape = '{"org": "<org>"}'
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as e:
+        raise ProjectFileError(f"{path} is not valid JSON ({e}); it should hold {shape}.")
+    org = data.get("org") if isinstance(data, dict) else None
+    if not isinstance(org, str) or not org.strip():
+        raise ProjectFileError(f"{path} names no org; it should hold {shape}.")
+    return org.strip()
+
+
+def named_org() -> tuple[str, str, str | None] | None:
+    """Steps 1-3 of the org order: ``(org, org_from, file)``, or None."""
+    if _org_flag:
+        return _org_flag, "--org", None
+    for var in ORG_ENV_VARS:
+        value = (os.environ.get(var) or "").strip()
+        if value:
+            return value, var, None
+    path = find_project_file()
+    if path is not None:
+        return read_project_org(path), PROJECT_FILE, str(path)
+    return None
 
 
 class CLIAuthManager:
-    """API keys for the CLI: device-flow login, profiles per org, the env var."""
+    """API keys for the CLI: device-flow login, a profile per org, the env var."""
 
     CONFIG_DIR = Path.home() / ".dataspring"
     CREDENTIALS_FILE = CONFIG_DIR / "credentials.json"
@@ -89,9 +210,10 @@ class CLIAuthManager:
     # -- stored profiles -------------------------------------------------
 
     def _load(self) -> dict:
-        """``{current, profiles: {org: {api_key, key_id, org_name, email}}}``;
-        empty for none, or for what an older CLI stored (Google credentials,
-        or CLI tokens): those sign nobody in now."""
+        """``{profiles: {org: {api_key, key_id, org_name, email}}}``; empty
+        for none, or for what an older CLI stored (Google credentials, or CLI
+        tokens): those sign nobody in now. A ``current`` an older CLI wrote
+        (``auth use``) is ignored: nothing machine-wide picks the org (D-99)."""
         if not self.CREDENTIALS_FILE.exists():
             return {}
         try:
@@ -101,6 +223,7 @@ class CLIAuthManager:
         return data if isinstance(data.get("profiles"), dict) else {}
 
     def _save(self, data: dict) -> None:
+        data.pop("current", None)
         self.CREDENTIALS_FILE.write_text(json.dumps(data, indent=2))
         self.CREDENTIALS_FILE.chmod(0o600)
 
@@ -115,19 +238,72 @@ class CLIAuthManager:
     def profiles(self) -> dict[str, dict]:
         return self._load().get("profiles", {})
 
-    def current_org(self) -> str | None:
-        return self._load().get("current")
+    # -- which org, which key (hub D-99) ---------------------------------
 
-    def use(self, org_id: str) -> dict:
-        """Make the stored profile for ``org_id`` current."""
-        data = self._load()
-        if org_id not in data.get("profiles", {}):
-            raise AuthenticationError(
-                f"No key for {org_id} on this machine. Run 'dataspring auth login' and approve {org_id}."
-            )
-        data["current"] = org_id
-        self._save(data)
-        return data["profiles"][org_id]
+    def resolve(self) -> ResolvedOrg:
+        """The org and key for this command, in the D-99 order (module doc).
+
+        Raises:
+            Refused: ``not_signed_in`` (no key at all, or none stored for the
+                org named), ``org_required`` (several stored, none named;
+                never a prompt), ``org_mismatch`` (``DATASPRING_API_KEY`` is
+                a key for another org than the one named).
+            ProjectFileError: a ``.forspring.json`` that names no org.
+        """
+        named = named_org()
+        env_key = os.environ.get(ENV_KEY)
+        profiles = self.profiles()
+
+        if env_key:
+            stored_org = next((org for org, p in profiles.items() if p.get("api_key") == env_key), None)
+            if named is None:
+                return ResolvedOrg(env_key, stored_org, FROM_KEY)
+            org, source, path = named
+            key_org = stored_org or self._key_org(env_key)
+            if key_org != org:
+                raise Refused(
+                    "org_mismatch",
+                    f"DATASPRING_API_KEY is a key for '{key_org}', but {source} names '{org}'.",
+                    f"Name '{key_org}', or set DATASPRING_API_KEY to a key for '{org}' "
+                    "(or unset it to use a stored key).",
+                )
+            return ResolvedOrg(env_key, org, source, path)
+
+        if not profiles:
+            raise _not_signed_in()
+        if named is not None:
+            org, source, path = named
+            profile = profiles.get(org)
+            if profile is None:
+                raise Refused(
+                    "not_signed_in",
+                    f"No key for '{org}' on this machine ({source} names it); "
+                    f"stored: {', '.join(sorted(profiles))}.",
+                    f"Run 'dataspring auth login' and approve {org}, or name one of the stored orgs.",
+                )
+            return ResolvedOrg(profile["api_key"], org, source, path)
+        if len(profiles) == 1:
+            org, profile = next(iter(profiles.items()))
+            return ResolvedOrg(profile["api_key"], org, FROM_ONLY_PROFILE)
+        raise Refused(
+            "org_required",
+            "Several organizations have keys on this machine and this command names none: "
+            f"{', '.join(sorted(profiles))}.",
+            f"Name one: {NAME_AN_ORG}.",
+        )
+
+    def _key_org(self, key: str) -> str | None:
+        """The org a key not stored here belongs to, as the server says.
+        Synchronous: :meth:`resolve` runs inside the async commands too."""
+        r = httpx.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"}, timeout=15.0)
+        return self._me_answer(r).get("org_id")
+
+    def resolved_org(self) -> str | None:
+        """The org a command here would use, or None when none resolves."""
+        try:
+            return self.resolve().org_id
+        except AuthenticationError:
+            return None
 
     # -- login -----------------------------------------------------------
 
@@ -167,14 +343,15 @@ class CLIAuthManager:
                 self._add_profile(data, body, body.get("email"))
                 for other in body.get("other_orgs") or []:
                     self._add_profile(data, other, body.get("email"))
-                data["current"] = body["org_id"]
                 self._save(data)
                 if body.get("email"):
                     self._save_config({"email": body["email"]})
-                return await self.get_user()
+                # The approved org's key: the one this login is about, whatever
+                # else is stored.
+                return self._context(await self._me(body["api_key"]))
             error = (r.json() or {}).get("error") if r.headers.get("content-type", "").startswith("application/json") else None
-            if error == "authorization_pending":
-                continue
+            if error in ("authorization_pending", "temporarily_unavailable"):
+                continue  # temporarily_unavailable: the Forspring account did not answer; the approval waits
             if error == "slow_down":
                 interval += 5
                 continue
@@ -188,36 +365,52 @@ class CLIAuthManager:
         me = await self._me(key)
         data = self._load()
         self._add_profile(data, {"api_key": key, "key_id": None, "org_id": me["org_id"], "org_name": me.get("org_name")}, me.get("email"))
-        data["current"] = me["org_id"]
         self._save(data)
         return self._context(me)
 
     # -- using the key ---------------------------------------------------
 
     def get_access_token(self) -> str:
-        """The key requests carry: ``DATASPRING_API_KEY`` if set, else the current profile's.
+        """The key this command sends: ``DATASPRING_API_KEY`` if set, else the
+        stored key for the org :meth:`resolve` names.
 
         Raises:
-            AuthenticationError: If not logged in
+            Refused: not signed in, no org named among several, or a mismatch
         """
-        if os.environ.get(ENV_KEY):
-            return os.environ[ENV_KEY]
-        data = self._load()
-        profile = data.get("profiles", {}).get(data.get("current") or "")
-        if not profile:
-            raise AuthenticationError("Not logged in. Run 'dataspring auth login' first.")
-        return profile["api_key"]
+        return self.resolve().key
 
     async def _me(self, key: str) -> dict:
         async with httpx.AsyncClient(timeout=15.0) as client:
             r = await client.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"})
+        return self._me_answer(r)
+
+    @staticmethod
+    def _me_answer(r: httpx.Response) -> dict:
+        """``GET /api/me``'s body, or the refusal it answered with (D-99)."""
+        if r.status_code == 200:
+            return r.json()
+        try:
+            body = r.json()
+        except ValueError:
+            body = None
+        refusal = from_body(body)
+        if refusal is not None:
+            raise Refused(refusal.reason, refusal.note, refusal.fix)
         if r.status_code == 401:
-            raise AuthenticationError("This key is unknown or revoked. Run 'dataspring auth login' again.")
+            raise _not_signed_in("This key is unknown, revoked or expired.")
+        # ``note`` since tick 3sb, ``detail`` from older servers and FastAPI.
+        detail = (body.get("note") or body.get("detail")) if isinstance(body, dict) else None
         if r.status_code == 403:
-            raise AuthenticationError(r.json().get("detail", "Access denied"))
-        if r.status_code != 200:
-            raise AuthenticationError(f"Failed to resolve user context (HTTP {r.status_code})")
-        return r.json()
+            text = str(detail or "Access denied")
+            raise Refused(
+                classify(text) or "not_a_member", text,
+                "An owner or admin of the org fixes this at https://account.forspring.ai; "
+                "or run 'dataspring auth login' again.",
+            )
+        if r.status_code == 503:
+            raise Refused("account_unavailable", str(detail or "The Forspring account cannot be reached."),
+                          EN["account_unavailable"]["fix"])
+        raise AuthenticationError(f"Failed to resolve user context (HTTP {r.status_code})")
 
     @staticmethod
     def _context(me: dict) -> "UserContext":
@@ -229,6 +422,22 @@ class CLIAuthManager:
         """The person and the key's org, as ``GET /api/me`` reports them."""
         return self._context(await self._me(self.get_access_token()))
 
+    async def whoami(self) -> dict:
+        """D-99's ``whoami --json``: the person, the org, where the org came
+        from (:class:`ResolvedOrg`'s ``org_from``), the role."""
+        resolved = self.resolve()
+        me = await self._me(resolved.key)
+        out = {
+            "person": me.get("email"),
+            "org": me.get("org_id"),
+            "org_name": me.get("org_name"),
+            "org_from": resolved.org_from,
+            "role": me.get("org_role"),
+        }
+        if resolved.org_file:
+            out["org_file"] = resolved.org_file
+        return out
+
     async def logout(self):
         """Revoke every stored key on the server, then forget them."""
         for profile in self.profiles().values():
@@ -245,10 +454,9 @@ class CLIAuthManager:
             self.CONFIG_FILE.unlink()
 
     def is_logged_in(self) -> bool:
-        if os.environ.get(ENV_KEY):
-            return True
-        data = self._load()
-        return bool(data.get("profiles", {}).get(data.get("current") or ""))
+        """A key exists to use: ``DATASPRING_API_KEY`` or a stored one (which
+        one a command uses is :meth:`resolve`'s)."""
+        return bool(os.environ.get(ENV_KEY)) or bool(self.profiles())
 
     def get_stored_email(self) -> str | None:
         """Get stored email from config (doesn't validate the key)."""

cli/bundled_manifest.py

@@ -6,7 +6,7 @@ the server's to say whether the server has operations this CLI does not
 know. tests/test_skills_surface.py asserts it is current.
 """
 
-MANIFEST_HASH = "eacbe5d755f415a814b50b568eb105ff60693b92fe1ce44d30e39f71670d15d0"
+MANIFEST_HASH = "b9fdc845fd9d3a22cea19e234b330e7e41d17f5d5ba6b5e1c713123d38109a6d"
 TOOL_KEYS = (
     "business_context_edit",
     "semantic_model_edit",

cli/contract.py

@@ -636,6 +636,18 @@ class DeployDatacoreAction(DispatchParams):
         ),
     )
     note: str | None = Field(default=None, description="Why, recorded on the learned trail")
+    then_build: bool = Field(
+        default=False,
+        description=(
+            "When the deploy changed any file under models/, also queue a models-only build (the `build` action) "
+            "of the newly deployed snapshot on the raw tables already loaded; build_select narrows it. "
+            "Without it, a deploy that changed models answers with the command that does it"
+        ),
+    )
+    build_select: str | None = Field(
+        default=None,
+        description="With then_build: the dbt selector to rebuild (default: every model, `fqn:*`)",
+    )
 
 
 class RunWindowParams(DispatchParams):
@@ -669,6 +681,27 @@ class RunPipelineAction(DispatchParams):
     )
 
 
+class BuildModelsAction(DispatchParams):
+    """Rebuild the deployed dbt models on the raw tables already loaded: no resource is loaded."""
+
+    action: Literal["build"]
+    pipeline: str | None = Field(
+        default=None,
+        description=(
+            "A deployed pipeline whose `then` block names what to build (its dbt_select, dbt_exclude and tests). "
+            "Omit to build every model of the deployed project"
+        ),
+    )
+    select: str | None = Field(
+        default=None,
+        description=(
+            "A dbt selector (`dbt build --select`), e.g. `marts.finance+` or `+fct_postings`; replaces the "
+            "pipeline's dbt_select and dbt_exclude. Default: the pipeline's then.dbt_select, or every model "
+            "(`fqn:*`) when no pipeline is named"
+        ),
+    )
+
+
 class ResetPipelineAction(DispatchParams):
     action: Literal["reset"]
     pipeline: str = Field(description="The pipeline whose dlt state and raw tables to remove")
@@ -689,7 +722,12 @@ class CancelRunAction(DispatchParams):
 
 
 DatacoreRunAction = Annotated[
-    CheckDatacoreAction | DeployDatacoreAction | RunPipelineAction | ResetPipelineAction | CancelRunAction,
+    CheckDatacoreAction
+    | DeployDatacoreAction
+    | RunPipelineAction
+    | BuildModelsAction
+    | ResetPipelineAction
+    | CancelRunAction,
     Field(discriminator="action"),
 ]
 
@@ -715,8 +753,10 @@ _PERIOD_DOC = (
 
 _COMPARE_TO_DOC = (
     "Compare the window against the one before it (previous_period, stepped "
-    "back by whole calendar periods when the window is whole ones) or the same "
-    "window a year earlier (same_period_last_year). The deltas come back "
+    "back by whole calendar periods when the window is whole ones, and by as "
+    "many periods as it touches, keeping its position, when it cuts a period "
+    "short: a year to date compares with the same days a year earlier) or the "
+    "same window a year earlier (same_period_last_year). The deltas come back "
     "BESIDE the values - each metric column gains <metric>__previous, "
     "<metric>__delta and <metric>__delta_pct - so there is no second result "
     "set to line up and no arithmetic to do. `comparison_period` says which "
@@ -1122,7 +1162,8 @@ class RunSqlParams(DispatchParams):
         description=(
             "One SQL statement (BigQuery Standard SQL on a managed warehouse). "
             "Name tables as <org>_marts.<table>, <org>_core.<table> or "
-            "<org>_staging.<table>; the identity it runs as can read those and "
+            "<org>_staging.<table>, <org> being the organization id with every "
+            "hyphen as an underscore (acme-dk is acme_dk_marts); the identity it runs as can read those and "
             "nothing else, so a write or a reach outside them is refused by "
             "the warehouse."
         )
@@ -1164,9 +1205,10 @@ class CreateTenantAction(DispatchParams):
     slug: str = Field(
         description=(
             "The tenant id, and therefore the organization id and the name in "
-            "every Google Cloud resource it owns (t-<slug>@, <slug>_raw, "
+            "every Google Cloud resource it owns, each derived from it by "
+            "services.tenants (t-<slug>@, <slug>_raw with hyphens as underscores, "
             "datacore-runner--<slug>, gs://dataspring-tenants/<slug>/). "
-            "Lower-case [a-z0-9-], at most 20 characters. Choose it "
+            "Lower-case [a-z0-9-], at most 63 characters. Choose it "
             "deliberately: it cannot be renamed afterwards."
         )
     )