@malloy-publisher/server 0.9.7 → 0.9.9

package/dist/app/api-doc.yaml

@@ -65,16 +65,28 @@ tags:
       distribution
   - name: models
     description: Malloy model access and compilation operations
+  - name: reports
+    description:
+      Reports - any `.malloy` file in a package carrying an artifact tag,
+      wherever it lives, with a linear or grid layout - their listing,
+      manifests, and cells
   - name: notebooks
-    description: Malloy notebook access and execution operations
+    description: Deprecated aliases for the linear reports. Use the `reports` routes.
   - name: dashboards
-    description:
-      Discovery and manifests for `# artifact` dashboards - layout, tiles, and
-      the given specs behind their controls
+    description: Deprecated aliases for the grid reports. Use the `reports` routes.
   - name: data-apps
     description:
       In-package HTML data apps (static pages served from a package's public/
       directory)
+  - name: skills
+    description:
+      Agent skills in force for a package - the bundled guides plus the package's
+      own `skills/`, with the package's copy replacing a bundled one of the same
+      name
+  - name: agents
+    description:
+      Agents a package declares in `publisher.json`, resolved to their
+      instructions, skill files and schedules (served, never run)
   - name: databases
     description: Embedded database management and access
   - name: watch-mode
@@ -1635,11 +1647,10 @@ paths:
 
         On a package with a surface (a root `index.malloy`, or a legacy `explores`), only the
         files on that surface are listed, unless `includeHiddenFilesAndSources` is true. With it, every
-        model file is listed, and `isHidden` marks the ones the package hides. Dashboard files
-        are listed by the dashboards route either way. Served notebooks (a `.malloy` at the top of
-        `notebooks/` or `dashboards/` whose model-level `## artifact` tag says `kind=notebook`, or
-        names no `kind` and sits under `notebooks/`) are not models here, with or without a
-        surface; they are listed by list-notebooks.
+        model file is listed, and `isHidden` marks the ones the package hides. Reports (any
+        `.malloy` outside `public/` carrying an artifact tag, other than the root `index.malloy`;
+        see list-reports) are listed by list-reports. A grid report is not a model here on a
+        package with a surface; a linear report is not a model here with or without one.
       parameters:
         - name: environmentName
           in: path
@@ -1694,15 +1705,14 @@ paths:
         On a package with a surface (a root `index.malloy`, or a legacy `explores`), a file off
         that surface answers 404 with the same message a query to it gets, unless
         `includeHiddenFilesAndSources` is true. With it, the file is returned with its `sourceText`, whatever
-        sources the text names. Dashboard files and served notebooks (a `.malloy` at the top of
-        `notebooks/` or `dashboards/` whose model-level `## artifact` tag says `kind=notebook`, or
-        names no `kind` and sits under `notebooks/`) are always returned. A package with no surface, or with
+        sources the text names. Reports (see list-reports), wherever they live in the package,
+        are always returned. A package with no surface, or with
         `queryableSources: "all"`, returns every file. For a file it returns, `modelDef.contents` and `modelDef.exports`,
         `modelInfo`, `sources` and `sourceInfos` are limited to the names the file publishes, so
         the surface file does not carry the hidden sources it imports. A join to a hidden source
         keeps only its name and the names and types of its fields. `sourceText` is left out
         when the text names a source the file does not publish, unless
-        `includeHiddenFilesAndSources` is true; the text of a dashboard is always returned.
+        `includeHiddenFilesAndSources` is true; the text of a report is always returned.
       parameters:
         - name: environmentName
           in: path
@@ -1750,15 +1760,29 @@ paths:
       tags:
         - models
       operationId: update-model-source
-      summary: Write a dashboard or notebook file into the package
+      summary: Write a report file into the package
       description: |
-        Writes the Malloy text of a dashboard file — `dashboards/<slug>.malloy` —
-        or a notebook file — `notebooks/<slug>.malloy`, which must carry an
-        `## artifact` tag (an untagged file there is a shared include and is
-        refused with 400, and so is a write over an existing file that is
-        not a notebook) — the only paths this endpoint accepts,
-        into the package, and reloads the package in place so it is served from
-        the new text. This is the dashboard and notebook builder's save.
+        Writes the Malloy text of a report into the package, and reloads the
+        package in place so it is served from the new text. This is the report
+        builder's save. A report is any `.malloy` file carrying an artifact tag
+        (see list-reports), of either layout, wherever it lives in the package.
+
+        What it accepts:
+
+        - CREATE (no `expectedHash`): any `.malloy` path in the package that
+          does not exist yet, outside `public/`, and never the root
+          `index.malloy`. Missing directories are created, inside the package
+          root only. The text must carry an artifact tag (`## artifact`, or the
+          deprecated query-level `# artifact`): an `artifact` property anywhere
+          on a tag line, outside a string. Text without one is refused with 400.
+        - REPLACE (with `expectedHash`): only a file the package currently reads
+          as an editable report: a tagged `.malloy` report of either layout,
+          including a tagged grid report that has no tiles yet. A model, an
+          untagged file, a `.malloynb`, the root `index.malloy` and anything in
+          `public/` cannot be overwritten, wherever they live, and answer 400.
+
+        Two reports may share a basename in different directories; a report is
+        identified by its path, so a taken basename is not refused.
 
         The text is compiled first, as the file, and refused with its problems
         when it does not compile; nothing is written. The write is atomic (a
@@ -1776,21 +1800,16 @@ paths:
         merged: the caller re-opens and reapplies its change. Omit it to CREATE
         the file: a file that already exists is then refused with 409 too, so
         an unconditional overwrite is not something a caller can ask for by
-        leaving a field out. A notebook path over an existing file the package
-        does not serve as a notebook answers 400 instead, with or without a
-        hash, because that check comes before the hash. The check, the write,
+        leaving a field out. A path over an existing file the package does not
+        read as a report answers 400 instead, with or without a hash, because
+        that check comes before the hash. The check, the write,
         the reload and the restore all happen under one hold of the package
         lock, so two saves racing on one file cannot both pass the check, and a
         rollback cannot revert the other writer's text instead of its own.
 
-        A dashboard whose name (the file's basename) another file already holds
-        is refused with 409 before anything is written, since the name is its
-        URL and its `# drill` target. A `dashboards/` file whose text has no
-        `# artifact` or `## artifact` tag (an `artifact` property anywhere on a
-        tag line, outside a string) is refused with 400 before anything is
-        written; a tag only inside a block comment passes that check but the
-        compiled model carries none, so it is rolled back and answers 500. A
-        tagged dashboard with no tiles saves but is not served until it has one.
+        A tag only inside a block comment passes the tag check but the compiled
+        model carries none, so it is rolled back and answers 500. A tagged grid
+        report with no tiles saves but is not served until it has one.
 
         A create answers 201 and an update 200; `created` in the body says the
         same thing.
@@ -1813,7 +1832,7 @@ paths:
             type: string
         - name: path
           in: path
-          description: The file, `dashboards/<slug>.malloy` or `notebooks/<slug>.malloy`
+          description: The report file's path in the package, such as `sales/q3.malloy`
           required: true
           schema:
             $ref: "#/components/schemas/PathPattern"
@@ -1852,9 +1871,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "409":
           description:
-            The file changed since the caller opened it, already exists and
-            no `expectedHash` was sent, or is a dashboard whose name another
-            file already holds
+            The file changed since the caller opened it, or already exists and
+            no `expectedHash` was sent
           content:
             application/json:
               schema:
@@ -1977,9 +1995,11 @@ paths:
         that is both gated and hidden from the caller answers 404 for the whole
         request, as it does without a document. In a document, problem positions
         are lines of the submitted text, problems carry no `model` tag, and
-        `includeSql` returns no `sql`. A tag that names no `kind` is a dashboard
-        when it lists `tiles` or carries a `dashboard { … }` grid tag, and a
-        notebook otherwise, since submitted text has no folder to take a kind from.
+        `includeSql` returns no `sql`. The document's `layout` follows the one
+        rule every report follows (see list-reports): the tag's `layout=`, else
+        its deprecated `kind=` (`dashboard` is grid, `notebook` is linear), else
+        grid when the tag lists `tiles` or carries a `dashboard { … }` grid tag,
+        else linear. Where a file lives never decides it.
       parameters:
         - name: environmentName
           in: path
@@ -2027,42 +2047,36 @@ paths:
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
-  /environments/{environmentName}/packages/{packageName}/dashboards:
+  /environments/{environmentName}/packages/{packageName}/reports:
     get:
       tags:
-        - dashboards
-      operationId: list-dashboards
-      summary: List package dashboards
+        - reports
+      operationId: list-reports
+      summary: List package reports
       description: |
-        Lists the dashboards in the specified package — every tagged `.malloy`
-        file at the top of `dashboards/` or `notebooks/` carrying an
-        `# artifact` (or model-level `## artifact`) annotation whose `kind` is
-        `dashboard`, or names none under `dashboards/`. A `kind=notebook` file is
-        listed as a notebook instead, whichever folder it sits in. A file with
-        no artifact tag is a shared include and is not listed, whether or not it
-        compiles.
-
-        A tagged dashboard that failed to compile is listed carrying its
-        `error` where that state can arise at all, so a broken dashboard is
-        visibly broken rather than silently absent. In practice it rarely does:
-        a package whose model fails to compile is not loaded, and a reload that
-        would break one is refused and leaves the previously loaded package
-        serving, so `error` is only reachable on the paths that keep per-model
-        placeholders. Treat it as present-but-uncommon rather than the normal
-        way a broken dashboard surfaces.
-
-        Every tagged dashboard is listed, whatever the package's surface. To
-        hide one, remove its `# artifact` tag. On a package with a surface (a
-        root `index.malloy`, or a legacy `explores`) with `queryableSources`
-        left at `"declared"`, a dashboard's tiles, its single query and its
-        filter `suggest` queries may read only sources the surface exports. A
-        source the dashboard declares on top of a surface source may be read;
-        one over a hidden source may not. The dashboard file's own
-        `export {}` and named queries add nothing to the surface. A tile over a
-        hidden source answers 404 when it runs, and the package's `warnings`
-        report each such tile, single query and suggest, with severity
-        `error`, as of the last load, naming the source and the fix. Under
-        `"all"` nothing is refused, so the situation does not arise.
+        Lists every report in the package, in path order. A report is a
+        `.malloy` file anywhere in the package, outside `public/`, that carries
+        an artifact tag: a model-level `## artifact`, or the deprecated
+        query-level `# artifact` on a `query:`. The package's root
+        `index.malloy` is never a report (it is the surface). A legacy
+        `.malloynb` is also a report, linear and read-only. Where a file lives
+        carries no meaning: `dashboards/` and `notebooks/` are ordinary
+        directory names. Everything else is an ordinary model, which a report
+        may import.
+
+        A report's `layout` is decided by its tags, first match wins: the
+        tag's `layout=` (`grid` or `linear`); else the deprecated `kind=`
+        (`dashboard` is grid, `notebook` is linear); else grid for a
+        query-level `# artifact`; else grid for a model-level tag that lists
+        `tiles` or carries a `dashboard { … }` grid tag; else linear.
+
+        A report is identified by its `path`. `name`, its basename, is a
+        display label only: two reports may share one.
+
+        Every report is listed whatever the package's surface; the surface
+        limits what its tiles and cells may read, not whether it is listed. A
+        report that failed to compile is listed with its `error`. A tagged grid
+        report with no tiles yet is not served and not listed.
       parameters:
         - name: environmentName
           in: path
@@ -2084,13 +2098,13 @@ paths:
             $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: A list of dashboards in the package
+          description: The reports in the package
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  $ref: "#/components/schemas/Dashboard"
+                  $ref: "#/components/schemas/Report"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
@@ -2102,19 +2116,24 @@ paths:
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
-  /environments/{environmentName}/packages/{packageName}/dashboards/{dashboardName}:
+  /environments/{environmentName}/packages/{packageName}/reports/{path}:
     get:
       tags:
-        - dashboards
-      operationId: get-dashboard
-      summary: Get a dashboard manifest
+        - reports
+      operationId: get-report
+      summary: Get a report manifest
       description: |
-        Retrieves everything a viewer needs to render one dashboard: the artifact
-        tag's declarations plus the control contract derived from the givens its
-        query references. Running the dashboard needs no further endpoint — its
-        query, each tile, and each control's suggest query all run
-        through the model query endpoint with `givens`, using the manifest's
-        `path` as the model.
+        Everything a viewer needs to render one report, addressed by its path in
+        the package, including its extension, exactly as list-reports gives
+        it (`sales/q3.malloy`). A report written as tiles, of either layout, carries the
+        manifest fields (`tiles` or `query`, `dashboardColumns`,
+        `startingGivens`, `autorun`, `givens`): its tiles run through the model
+        query endpoint with `givens`, using `path` as the model. A linear
+        report written as `run:` cells, or a `.malloynb`, carries `notebook`
+        instead: its cells as get-notebook returned them. A `.malloy` report's
+        cells run through the model query endpoint, each cell's `text` as
+        `query` and `path` as the model; a `.malloynb`'s through the
+        deprecated execute-notebook-cell.
       parameters:
         - name: environmentName
           in: path
@@ -2128,19 +2147,14 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
-        - name: dashboardName
+        - name: path
           in: path
           description: >-
-            The dashboard's name: its filename basename. Conventionally letters,
-            digits, "-" and "_", and a package is warned when one of its
-            dashboards falls outside that. It is NOT constrained to it, because
-            the name comes from a filename rather than being chosen: a file such
-            as `dashboards/v1.2.malloy` is served, and its published `resource`
-            carries the name percent-encoded. Send it percent-encoded.
+            The report's path within the package, including `.malloy` (or
+            `.malloynb`): the `path` list-reports returns.
           required: true
           schema:
             type: string
-            minLength: 1
         - name: versionId
           in: query
           description: Version identifier for the package
@@ -2149,11 +2163,11 @@ paths:
             $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: The dashboard manifest
+          description: The report manifest
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/DashboardManifest"
+                $ref: "#/components/schemas/ReportManifest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
@@ -2165,19 +2179,29 @@ paths:
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
-  /environments/{environmentName}/packages/{packageName}/notebooks:
+  /environments/{environmentName}/packages/{packageName}/skills:
     get:
       tags:
-        - notebooks
-      operationId: list-notebooks
-      summary: List package notebooks
+        - skills
+      operationId: list-skills
+      summary: List the agent skills in force for a package
       description: |
-        Retrieves a list of all Malloy notebooks within the specified package: every
-        `.malloynb` file, and every `.malloy` file at the top of `notebooks/` or `dashboards/`
-        whose model-level `## artifact` tag says `kind=notebook` (or names no `kind` and sits
-        under `notebooks/`). Each notebook entry includes the relative path,
-        package name, title, description, and any compilation or reading error. This endpoint
-        is useful for discovering available notebooks and checking their status.
+        Lists the agent skills that apply to this package: the guides bundled
+        with this server, plus any the package ships under `skills/`.
+
+        Resolution is name shadowing. A package skill whose `name` matches a
+        bundled skill REPLACES it for this package; one with a new name is
+        added. Nothing is merged, because the server does not know which guides
+        the calling agent already holds and so cannot patch one. Read `origin`
+        on each entry to tell a replaced skill from the original.
+
+        Bodies are not returned here. Fetch one with
+        `GET .../skills/{skillName}`. An entry whose `name` contains a slash
+        (`<skill>/<stem>`) is a skill's on-demand reference file, addressed by
+        the pointer at the end of its parent's body.
+
+        The REST half of the `get_skill` MCP tool, for callers running
+        unattended.
       parameters:
         - name: environmentName
           in: path
@@ -2191,45 +2215,38 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: A list of notebooks in the package
+          description: The skills in force for the package
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  $ref: "#/components/schemas/Notebook"
+                  $ref: "#/components/schemas/SkillSummary"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
-  /environments/{environmentName}/packages/{packageName}/notebooks/{path}:
+  /environments/{environmentName}/packages/{packageName}/skills/{skillName}:
     get:
       tags:
-        - notebooks
-      operationId: get-notebook
-      summary: Get Malloy notebook cells
+        - skills
+      operationId: get-skill
+      summary: Get one agent skill, with its body
       description: |
-        Retrieves a Malloy notebook with its raw cell contents (markdown and code).
-        Cell execution should be done separately via the execute-notebook-cell endpoint.
-        A served notebook (a `.malloy` at the top of `notebooks/` or `dashboards/` whose
-        model-level `## artifact` tag says `kind=notebook`, or names no `kind` and sits under
-        `notebooks/`) answers here as well as a `.malloynb`.
-        On a package with a surface, the response shows only the sources the notebook may read.
+        Returns one skill in force for this package, including its full
+        Markdown. `skillName` is a name from the listing, exactly as spelled
+        there; a reference file is addressed as `<skill>/<stem>`. The slash may
+        be sent literally or as `%2F`; a literal `%` in a name must be sent as
+        `%25`.
+
+        404 when no skill of that name is in force.
       parameters:
         - name: environmentName
           in: path
@@ -2242,55 +2259,44 @@ paths:
           description: Name of the package
           required: true
           schema:
-            type: string
-        - name: path
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: skillName
           in: path
-          description: Path to notebook within the package.
+          description: >-
+            Skill name as returned by the listing. A reference file is
+            `<skill>/<stem>`; the slash may be literal or `%2F`.
           required: true
           schema:
             type: string
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: A Malloy notebook with raw cell contents.
+          description: The skill and its body
           content:
-            "application/json":
+            application/json:
               schema:
-                $ref: "#/components/schemas/RawNotebook"
+                $ref: "#/components/schemas/Skill"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
-  /environments/{environmentName}/packages/{packageName}/notebooks/{path}/cells/{cellIndex}:
+  /environments/{environmentName}/packages/{packageName}/agents:
     get:
       tags:
-        - notebooks
-      operationId: execute-notebook-cell
-      summary: Execute a specific notebook cell
+        - agents
+      operationId: list-agents
+      summary: List the agents a package declares
       description: |
-        Executes a specific cell in a Malloy notebook by index. For code cells, this compiles
-        and runs the Malloy code, returning query results and any new sources defined.
-        For markdown cells, this simply returns the cell content. A served notebook
-        (tagged `kind=notebook`, or untagged-kind under `notebooks/`) answers here as well as a
-        `.malloynb`.
+        Lists the agents declared under `agents` in the package's
+        `publisher.json` that passed validation, without instructions or
+        skills. An agent that failed validation is not listed; the package's
+        `warnings` say why. Empty when the manifest declares none.
 
-        On a package with a surface (a root `index.malloy`, or a legacy `explores`) with
-        `queryableSources` left at `"declared"`, a code cell may read only sources the surface
-        exports. A cell over a hidden source answers 404, and 404 rather than 403 even when the
-        source is also `#(authorize)`-gated. A source an earlier cell declares on top of a
-        published source still works. A cell's own source over a raw table (`duckdb.table(...)`
-        or `.sql(...)`) has no published source under it, so it is refused. The response shows
-        only the sources the notebook may read.
+        The REST half of the `get_agent` MCP tool.
       parameters:
         - name: environmentName
           in: path
@@ -2303,102 +2309,39 @@ paths:
           description: Name of the package
           required: true
           schema:
-            type: string
-        - name: path
-          in: path
-          description: Path to notebook within the package
-          required: true
-          schema:
-            type: string
-        - name: cellIndex
-          in: path
-          description: Index of the cell to execute (0-based)
-          required: true
-          schema:
-            type: integer
-        - name: versionId
-          in: query
-          description: Version identifier for the package
-          required: false
-          schema:
-            $ref: "#/components/schemas/VersionIdPattern"
-        - name: filter_params
-          in: query
-          deprecated: true
-          description: |
-            **DEPRECATED**: Use `givens` (native Malloy runtime parameters) instead.
-            Targets the deprecated `#(filter)` annotation path. See docs/givens.md
-            for migration recipes.
-
-            JSON-encoded filter parameter values keyed by filter name.
-          required: false
-          schema:
-            type: string
-        - name: bypass_filters
-          in: query
-          deprecated: true
-          description: |
-            **DEPRECATED**: Use `givens` (native Malloy runtime parameters) instead.
-            See docs/givens.md for migration recipes.
-
-            When true, skip filter injection entirely.
-          required: false
-          schema:
-            type: string
-            enum:
-              - "true"
-              - "false"
-        - name: givens
-          in: query
-          description:
-            A `GivenValues` object, JSON-encoded so it can travel in a query
-            string. Values are typed as `GivenValues` describes them, not
-            string-encoded as `EncodedGivenValues` would be. The parameter keeps
-            its name for compatibility; the schema it carries is the one named
-            here.
-          required: false
-          schema:
-            type: string
+            $ref: "#/components/schemas/IdentifierPattern"
       responses:
         "200":
-          description: Cell execution result
+          description: The agents the package declares
           content:
-            "application/json":
+            application/json:
               schema:
-                $ref: "#/components/schemas/NotebookCellResult"
-        "400":
-          $ref: "#/components/responses/BadRequest"
+                type: array
+                items:
+                  $ref: "#/components/schemas/AgentSummary"
         "401":
           $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
         "404":
           $ref: "#/components/responses/NotFound"
-        "413":
-          $ref: "#/components/responses/PayloadTooLarge"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
-        "424":
-          $ref: "#/components/responses/ConnectionUnavailable"
-        "502":
-          $ref: "#/components/responses/DatabaseUnreachable"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
-        "504":
-          $ref: "#/components/responses/GatewayTimeout"
 
-  /environments/{environmentName}/packages/{packageName}/databases:
+  /environments/{environmentName}/packages/{packageName}/agents/{agentName}:
     get:
       tags:
-        - databases
-      operationId: list-databases
-      summary: List embedded databases
+        - agents
+      operationId: get-agent
+      summary: Get one agent, resolved
       description: |
-        Retrieves a list of all embedded databases within the specified package. These are typically
-        local data files read by DuckDB in place (.parquet, .csv, and .xlsx) that provide local data
-        storage for the package. Each database entry includes metadata about the database structure and content.
+        Returns one agent with its instructions, its own skill files and each
+        schedule's task text, plus `source`, which pins the package load and the
+        agent's own content so a runner can prove which bytes ran. Publisher
+        serves the definition and runs nothing: the caller's own harness
+        executes it, and schedules are never fired by the server.
+
+        404 when no agent of that name is served.
       parameters:
         - name: environmentName
           in: path
@@ -2412,48 +2355,63 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
-        - name: versionId
+        - name: agentName
+          in: path
+          description: >-
+            Agent name as returned by the listing. Names are 1-64 lowercase
+            letters, digits and single hyphens; any other value is a 404, not a
+            400.
+          required: true
+          schema:
+            type: string
+            pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
+            maxLength: 64
+        - name: skills
           in: query
-          description: Version identifier for the package
+          description: >-
+            `full` (the default) returns every skill file with its text.
+            `summary` returns each file's `relative_filepath` and `bytes`, plus
+            `name` and `description` for a `SKILL.md`, and no `file_contents`;
+            fetch a file with `GET .../agents/{agentName}/skills/{path}`. The
+            `source` pin is identical in both. Any other value, including an
+            empty one, is a 400.
           required: false
           schema:
-            $ref: "#/components/schemas/VersionIdPattern"
+            type: string
+            enum: [full, summary]
+            default: full
       responses:
         "200":
-          description: A list of embedded databases in the package
+          description: The resolved agent
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/Database"
+                $ref: "#/components/schemas/Agent"
+        "400":
+          $ref: "#/components/responses/BadRequest"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
-  /environments/{environmentName}/packages/{packageName}/data-apps:
+  /environments/{environmentName}/packages/{packageName}/agents/{agentName}/skills/{relativeFilepath}:
     get:
       tags:
-        - data-apps
-      operationId: list-data-apps
-      summary: List package data apps
+        - agents
+      operationId: get-agent-skill-file
+      summary: Get one of an agent's skill files
       description: |
-        Retrieves a list of all in-package HTML data apps (static pages served
-        from the package's public/ directory) within the specified package. Each
-        entry includes the relative path, the package name, a canonical resource
-        URL, and the title (extracted from the file's <title> tag, falling back
-        to the path). Used by the Publisher SPA to surface a clickable "Data
-        Apps" section on the package detail view, and by anyone who wants to
-        discover a package's data apps programmatically without scraping the
-        directory. Recursive depth is capped server-side to keep this cheap on
-        large packages.
+        Returns one file from the agent's resolved skill set, named by a
+        `relative_filepath` from `GET .../agents/{agentName}?skills=summary`
+        (for example `analyst-conventions/SKILL.md`), with the same `source`
+        pin as the full definition. The path is looked up in the resolved set,
+        never joined onto the filesystem.
+
+        404 when the agent or the file is not served.
       parameters:
         - name: environmentName
           in: path
@@ -2467,57 +2425,580 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - name: agentName
+          in: path
+          description: >-
+            Agent name as returned by the listing. Names are 1-64 lowercase
+            letters, digits and single hyphens; any other value is a 404, not a
+            400.
+          required: true
+          schema:
+            type: string
+            pattern: "^[a-z0-9]+(-[a-z0-9]+)*$"
+            maxLength: 64
+        - name: relativeFilepath
+          in: path
+          description: >-
+            A `relative_filepath` from the agent's skill summary. Slashes may be
+            sent literally or as `%2F`; a literal `%` in a name must be sent as
+            `%25`.
+          required: true
+          schema:
+            type: string
       responses:
         "200":
-          description: A list of data apps in the package
+          description: The skill file
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/DataApp"
-        "400":
-          $ref: "#/components/responses/BadRequest"
+                $ref: "#/components/schemas/AgentSkillRead"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
-        "501":
-          $ref: "#/components/responses/NotImplemented"
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
-  /environments/{environmentName}/packages/{packageName}/events:
+  # ── DEPRECATED ──────────────────────────────────────────────────────────
+  # The `…/dashboards*` and `…/notebooks*` routes, kept for clients that still
+  # read them, until a later release removes them. Use `…/reports*` above.
+  # Their schemas (`Dashboard`, `DashboardManifest`, `DashboardTile`,
+  # `Notebook`, `RawNotebook`) are in the deprecated section of the schemas;
+  # no report schema references them.
+  /environments/{environmentName}/packages/{packageName}/dashboards:
     get:
       tags:
-        - watch-mode
-      operationId: stream-package-events
-      summary: Stream package change events (SSE)
+        - dashboards
+      operationId: list-dashboards
+      deprecated: true
+      summary: List package dashboards (deprecated; use list-reports)
       description: |
-        Opens a Server-Sent Events (SSE) stream of file-change events for the
-        package, used by in-package HTML data apps (via the publisher.js
-        runtime) to live-reload when their sources are edited.
+        **DEPRECATED**: use list-reports, which lists every report of either
+        layout by path. This route lists the package's grid reports (see
+        list-reports for what makes a file a report and which layout it has),
+        wherever they live in the package. Two may share a `name`; their `path`
+        tells them apart. A file with no artifact tag is an ordinary model and is
+        not listed, whether or not it compiles.
+
+        **Contract change since reports.** This route used to list only
+        `.malloy` files directly under `dashboards/`, so every `name` was unique
+        and every `path` was `dashboards/<name>.malloy`. It now lists grid
+        reports from anywhere in the package (`sales/q3.malloy`,
+        `notebooks/x.malloy`, `a/b/c.malloy`), so `path` may have any depth and
+        `name` may repeat. Key on `path`.
 
-        This is a long-lived `text/event-stream` connection, not a JSON
-        endpoint, and is therefore not surfaced through the generated API
-        clients — consume it with an `EventSource`. The stream emits:
-          - `event: hello` (`data: connected`) once on connect.
-          - `event: mode` (`data: enabled|disabled`) reporting whether watch
-            mode is currently active for the environment. When `disabled`, no
-            `changed` events will follow until watch mode is started.
-          - `event: changed` (`data: changed`) each time a watched file in the
-            package changes.
-          - periodic `: heartbeat` comments to keep idle proxies from closing
-            the connection.
-      parameters:
-        - name: environmentName
-          in: path
-          description: Name of the environment
-          required: true
-          schema:
-            $ref: "#/components/schemas/IdentifierPattern"
+        A tagged dashboard that failed to compile is listed carrying its
+        `error` where that state can arise at all, so a broken dashboard is
+        visibly broken rather than silently absent. In practice it rarely does:
+        a package whose model fails to compile is not loaded, and a reload that
+        would break one is refused and leaves the previously loaded package
+        serving, so `error` is only reachable on the paths that keep per-model
+        placeholders. Treat it as present-but-uncommon rather than the normal
+        way a broken dashboard surfaces.
+
+        Every tagged dashboard is listed, whatever the package's surface. To
+        hide one, remove its `# artifact` tag. On a package with a surface (a
+        root `index.malloy`, or a legacy `explores`) with `queryableSources`
+        left at `"declared"`, a dashboard's tiles, its single query and its
+        filter `suggest` queries may read only sources the surface exports. A
+        source the dashboard declares on top of a surface source may be read;
+        one over a hidden source may not. The dashboard file's own
+        `export {}` and named queries add nothing to the surface. A tile over a
+        hidden source answers 404 when it runs, and the package's `warnings`
+        report each such tile, single query and suggest, with severity
+        `error`, as of the last load, naming the source and the fix. Under
+        `"all"` nothing is refused, so the situation does not arise.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: versionId
+          in: query
+          description: Version identifier for the package
+          required: false
+          schema:
+            $ref: "#/components/schemas/VersionIdPattern"
+      responses:
+        "200":
+          description: A list of dashboards in the package
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Dashboard"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/dashboards/{dashboardName}:
+    get:
+      tags:
+        - dashboards
+      operationId: get-dashboard
+      deprecated: true
+      summary: Get a dashboard manifest (deprecated; use get-report)
+      description: |
+        **DEPRECATED**: use get-report, which addresses a report by its path.
+        Retrieves everything a viewer needs to render one grid report: the
+        artifact tag's declarations plus the control contract derived from the
+        givens its query references. Running it needs no further endpoint — its
+        query, each tile, and each control's suggest query all run
+        through the model query endpoint with `givens`, using the manifest's
+        `path` as the model.
+
+        `dashboardName` is a basename, which is not an identity: it resolves
+        only when exactly one grid report in the package has it. When several
+        do, the answer is 409 naming every matching path; address the report
+        by path with get-report instead.
+
+        **Contract change since reports.** This route never answered 409
+        before: a dashboard lived directly under `dashboards/`, so its name was
+        unique. A grid report may now live anywhere, two may share a basename,
+        and a client of this route must handle 409. The match also covers grid
+        reports outside `dashboards/`.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: dashboardName
+          in: path
+          description: >-
+            The report's name: its filename basename. Conventionally letters,
+            digits, "-" and "_", and a package is warned when one of its
+            grid reports falls outside that. It is NOT constrained to it, because
+            the name comes from a filename rather than being chosen: a file such
+            as `v1.2.malloy` is served, and its published `resource`
+            carries the name percent-encoded. Send it percent-encoded.
+          required: true
+          schema:
+            type: string
+            minLength: 1
+        - name: versionId
+          in: query
+          description: Version identifier for the package
+          required: false
+          schema:
+            $ref: "#/components/schemas/VersionIdPattern"
+      responses:
+        "200":
+          description: The dashboard manifest
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DashboardManifest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description:
+            More than one grid report in the package has this basename. The
+            message names every matching path; use get-report with one.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/notebooks:
+    get:
+      tags:
+        - notebooks
+      operationId: list-notebooks
+      deprecated: true
+      summary: List package notebooks (deprecated; use list-reports)
+      description: |
+        **DEPRECATED**: use list-reports. Lists the package's linear reports (see
+        list-reports): every `.malloynb` file outside `public/`, and every tagged
+        `.malloy` report whose layout is linear, wherever it lives. Each entry
+        includes the relative path, package name, title, description, and any
+        compilation or reading error.
+
+        **Contract change since reports.** This route used to list `.malloy`
+        notebooks only directly under `notebooks/`. It now lists linear reports
+        from anywhere in the package, including `dashboards/` and nested
+        directories, and no longer lists a kindless tiled file in `notebooks/`,
+        which is now grid.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: versionId
+          in: query
+          description: Version identifier for the package
+          required: false
+          schema:
+            $ref: "#/components/schemas/VersionIdPattern"
+      responses:
+        "200":
+          description: A list of notebooks in the package
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Notebook"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/notebooks/{path}:
+    get:
+      tags:
+        - notebooks
+      operationId: get-notebook
+      deprecated: true
+      summary: Get Malloy notebook cells (deprecated; use get-report)
+      description: |
+        **DEPRECATED**: use get-report. Retrieves a linear report with its raw
+        cell contents (markdown and code). A `.malloy` report's cells run
+        through the model query endpoint (each cell's `text` as the query); a
+        `.malloynb`'s through execute-notebook-cell. A linear `.malloy`
+        report, wherever it lives, answers here as well as a `.malloynb`.
+        On a package with a surface, the response shows only the sources the notebook may read.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            type: string
+        - name: path
+          in: path
+          description: Path to notebook within the package.
+          required: true
+          schema:
+            type: string
+        - name: versionId
+          in: query
+          description: Version identifier for the package
+          required: false
+          schema:
+            $ref: "#/components/schemas/VersionIdPattern"
+      responses:
+        "200":
+          description: A Malloy notebook with raw cell contents.
+          content:
+            "application/json":
+              schema:
+                $ref: "#/components/schemas/RawNotebook"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+
+  /environments/{environmentName}/packages/{packageName}/notebooks/{path}/cells/{cellIndex}:
+    get:
+      tags:
+        - notebooks
+      operationId: execute-notebook-cell
+      deprecated: true
+      summary: Execute a specific notebook cell (deprecated)
+      description: |
+        **DEPRECATED**: removed with the other notebook routes. For a `.malloy`
+        report, run a cell through the model query endpoint instead: the
+        report's path as the model, the cell's `text` (from get-report) as
+        `query`, and `givens` in the body, which applies the same surface,
+        `#(authorize)` and row-level gates. A `.malloynb` has no other route.
+        Executes a specific cell in a linear report by index.
+        For code cells, this compiles and runs the Malloy code, returning query
+        results and any new sources defined. For markdown cells, this simply
+        returns the cell content. A linear `.malloy` report, wherever it lives,
+        answers here as well as a `.malloynb`.
+
+        On a package with a surface (a root `index.malloy`, or a legacy `explores`) with
+        `queryableSources` left at `"declared"`, a code cell may read only sources the surface
+        exports. A cell over a hidden source answers 404, and 404 rather than 403 even when the
+        source is also `#(authorize)`-gated. A source an earlier cell declares on top of a
+        published source still works. A cell's own source over a raw table (`duckdb.table(...)`
+        or `.sql(...)`) has no published source under it, so it is refused. The response shows
+        only the sources the notebook may read.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            type: string
+        - name: path
+          in: path
+          description: Path to notebook within the package
+          required: true
+          schema:
+            type: string
+        - name: cellIndex
+          in: path
+          description: Index of the cell to execute (0-based)
+          required: true
+          schema:
+            type: integer
+        - name: versionId
+          in: query
+          description: Version identifier for the package
+          required: false
+          schema:
+            $ref: "#/components/schemas/VersionIdPattern"
+        - name: filter_params
+          in: query
+          deprecated: true
+          description: |
+            **DEPRECATED**: Use `givens` (native Malloy runtime parameters) instead.
+            Targets the deprecated `#(filter)` annotation path. See docs/givens.md
+            for migration recipes.
+
+            JSON-encoded filter parameter values keyed by filter name.
+          required: false
+          schema:
+            type: string
+        - name: bypass_filters
+          in: query
+          deprecated: true
+          description: |
+            **DEPRECATED**: Use `givens` (native Malloy runtime parameters) instead.
+            See docs/givens.md for migration recipes.
+
+            When true, skip filter injection entirely.
+          required: false
+          schema:
+            type: string
+            enum:
+              - "true"
+              - "false"
+        - name: givens
+          in: query
+          description:
+            A `GivenValues` object, JSON-encoded so it can travel in a query
+            string. Values are typed as `GivenValues` describes them, not
+            string-encoded as `EncodedGivenValues` would be. The parameter keeps
+            its name for compatibility; the schema it carries is the one named
+            here.
+          required: false
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Cell execution result
+          content:
+            "application/json":
+              schema:
+                $ref: "#/components/schemas/NotebookCellResult"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "413":
+          $ref: "#/components/responses/PayloadTooLarge"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+        "424":
+          $ref: "#/components/responses/ConnectionUnavailable"
+        "502":
+          $ref: "#/components/responses/DatabaseUnreachable"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+        "504":
+          $ref: "#/components/responses/GatewayTimeout"
+
+  /environments/{environmentName}/packages/{packageName}/databases:
+    get:
+      tags:
+        - databases
+      operationId: list-databases
+      summary: List embedded databases
+      description: |
+        Retrieves a list of all embedded databases within the specified package. These are typically
+        local data files read by DuckDB in place (.parquet, .csv, and .xlsx) that provide local data
+        storage for the package. Each database entry includes metadata about the database structure and content.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: versionId
+          in: query
+          description: Version identifier for the package
+          required: false
+          schema:
+            $ref: "#/components/schemas/VersionIdPattern"
+      responses:
+        "200":
+          description: A list of embedded databases in the package
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Database"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/data-apps:
+    get:
+      tags:
+        - data-apps
+      operationId: list-data-apps
+      summary: List package data apps
+      description: |
+        Retrieves a list of all in-package HTML data apps (static pages served
+        from the package's public/ directory) within the specified package. Each
+        entry includes the relative path, the package name, a canonical resource
+        URL, and the title (extracted from the file's <title> tag, falling back
+        to the path). Used by the Publisher SPA to surface a clickable "Data
+        Apps" section on the package detail view, and by anyone who wants to
+        discover a package's data apps programmatically without scraping the
+        directory. Recursive depth is capped server-side to keep this cheap on
+        large packages.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      responses:
+        "200":
+          description: A list of data apps in the package
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/DataApp"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /environments/{environmentName}/packages/{packageName}/events:
+    get:
+      tags:
+        - watch-mode
+      operationId: stream-package-events
+      summary: Stream package change events (SSE)
+      description: |
+        Opens a Server-Sent Events (SSE) stream of file-change events for the
+        package, used by in-package HTML data apps (via the publisher.js
+        runtime) to live-reload when their sources are edited.
+
+        This is a long-lived `text/event-stream` connection, not a JSON
+        endpoint, and is therefore not surfaced through the generated API
+        clients — consume it with an `EventSource`. The stream emits:
+          - `event: hello` (`data: connected`) once on connect.
+          - `event: mode` (`data: enabled|disabled`) reporting whether watch
+            mode is currently active for the environment. When `disabled`, no
+            `changed` events will follow until watch mode is started.
+          - `event: changed` (`data: changed`) each time a watched file in the
+            package changes.
+          - periodic `: heartbeat` comments to keep idle proxies from closing
+            the connection.
+      parameters:
+        - name: environmentName
+          in: path
+          description: Name of the environment
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
         - name: packageName
           in: path
           description: Name of the package
@@ -3394,11 +3875,11 @@ components:
             paths relative to the package root. Only these models are listed
             via `listModels()`, and the surface is the union of their
             `export {}` closures. Every other .malloy file still compiles for
-            import/join resolution but is hidden. Notebooks and dashboards are
-            always listed regardless of this field, and a dashboard entry
-            needs no listing: a tagged dashboard listed here reads the surface
-            and adds nothing to it. An untagged file under `dashboards/` that
-            is listed is an ordinary surface file.
+            import/join resolution but is hidden. Reports are always listed
+            regardless of this field, and a report needs no listing: a report
+            listed here reads the surface and adds nothing to it, and the
+            package warns about it (`report-on-surface`). An untagged file
+            that is listed is an ordinary surface file, wherever it lives.
             DEPRECATED, still honored. Every non-empty value gets a load
             warning naming the replacement: a root `index.malloy` that imports
             the listed files and exports what they publish. `[]` is deprecated
@@ -3457,23 +3938,28 @@ components:
             `queryableSources: "declared"`, and a root file such as
             `Index.malloy` that differs from `index.malloy` only in case and
             so is ignored. A root `index.malloy` with no manifest keys gets no
-            warning. Dashboard findings: a
-            `dashboards/` file whose `# artifact` tag does not parse or does not
-            describe a dashboard, a tile or suggest query that does not resolve,
-            a `# drill` naming a destination that is not a dashboard, and a
-            tile, single query or filter suggest that reads a source the
-            surface does not export, so it won't load. Two dashboard findings are about Publisher rather
-            than about the package: one when a file carrying an artifact tag
-            could not be read and so is not served at all, and one when the lint
-            stops early, in which case the list must be read as incomplete
-            rather than as a clean package. Notebook findings: a `notebooks/`
-            file with an `## artifact` note whose cells could not be read, which
-            names the line and the fix and is reported with severity `error`,
-            because the notebook is served with that error instead of opening.
-            The same family carries findings on files under `notebooks/` and
-            `dashboards/`, each naming its line and the fix; they are computed
-            at discovery and are also returned by `/compile` at file and
-            package scope. Eight codes are `error` and fail `/compile`:
+            warning. Report findings (one lint pass per report, of either
+            layout, wherever it lives): a file whose artifact tag does not
+            parse or does not describe a report, a tile or suggest query that
+            does not resolve, a `# drill` naming a destination that is not a
+            report, and a tile, single query or filter suggest that reads a
+            source the surface does not export, so it won't load. A `# drill`
+            destination is a path from the package root (a bare name is a file
+            at the root); one that names no report is unresolved (`error`).
+            Curation findings: a root `index.malloy` carrying an artifact tag,
+            which is ignored (`index-is-not-a-report`, `error`); and a report
+            that `index.malloy` imports or `explores` lists
+            (`report-on-surface`, `warn`). Two report findings are about
+            Publisher rather than about the package: one when a file carrying
+            an artifact tag could not be read and so is not served at all, and
+            one when the lint stops early, in which case the list must be read
+            as incomplete rather than as a clean package. A linear report whose
+            cells could not be read gets a finding that names the line and the
+            fix and is reported with severity `error`, because it is served
+            with that error instead of opening. The per-file report findings
+            each name their line and the fix and carry a `code`; they are
+            computed at discovery and are also returned by `/compile` at file
+            and package scope. Eight codes are `error` and fail `/compile`:
             `notebook-statement-above-artifact` and `notebook-tag-above-artifact`
             (a statement or a tag above a served notebook's `## artifact`),
             `notebook-markdown-above-artifact` (a `(markdown)` annotation above
@@ -3484,9 +3970,21 @@ components:
             `notebook-markdown-attached-nowhere` (a `#(markdown)` annotation
             with no statement to take it), `notebook-artifact-unparsed` (an
             `## artifact` tag does not parse), and `notebook-cells-unreadable`
-            (the reader could not read a served notebook's cells). The rest are
-            `warn` (a mistyped `(markdown)` opener, a missing `kind=notebook`, a
-            block that never closes, and similar).
+            (the reader could not read a linear report's cells), plus
+            `report-kind-removed` (a tag that sets `kind=`, which is no longer
+            read, so the file is not a report; the finding names the `layout=`
+            to write) and `report-layout-unknown` (a `layout=` other than
+            `grid` or `linear`). The rest are `warn` (a mistyped `(markdown)`
+            opener, `report-layout-implicit` for a tag that names no layout and lists
+            no tiles, a block that never closes, and similar).
+            Skill and agent findings, all `warn`: a package skill under
+            `skills/` that is not served (unreadable or linked-out `SKILL.md`,
+            a frontmatter `name` that is not its directory name, a `skills/`
+            directory that links out of the package) or served with a gap (no
+            `description`, a `reference/` that cannot be listed or read); and
+            each agent the manifest declares that is not served, or is served
+            with a finding (an agent skill with no `description`, a skills
+            directory with no skills, an unreadable reference).
             Deprecated-format findings, all `warn`: each `.malloynb` notebook
             (`model` is its path), and each source a file declares deprecated
             `#(filter)` annotations on (`model` is that file, `subject` the
@@ -3582,8 +4080,8 @@ components:
                 description: >-
                   What the finding is about: the query or view a render finding
                   sits on (`by_carrier`, `flights -> by_carrier`), the source a
-                  materialization finding belongs to, or, for a dashboard
-                  finding, the dashboard's name or the `source.dimension` a
+                  materialization finding belongs to, or, for a report
+                  finding, the report's name or the `source.dimension` a
                   `# drill` is declared on. Absent when a finding sits on none
                   of those, either because it spans several, in which case the
                   message names them, or because it is about the lint itself
@@ -3591,13 +4089,33 @@ components:
               message:
                 type: string
                 description: A description of the problem.
+              code:
+                type: string
+                description: >-
+                  A stable identifier for the finding's family, for a client that
+                  acts on it rather than only showing it; absent for a family that
+                  has none yet. `deprecated-malloynb-notebook`: a `.malloynb`
+                  notebook, the deprecated cell format (one per file, `model`
+                  naming it). `deprecated-filter-annotation`: a source declaring
+                  deprecated `#(filter)` annotations (one per declaring source,
+                  `model` naming its file and `subject` the source).
+                  `report-name-ambiguous`: two or more grid reports share a
+                  basename, so the deprecated `GET …/dashboards/{name}` route
+                  answers 409 for it (one per name, `subject` naming it and the
+                  message every path; `warn`). The per-file
+                  report findings (`notebook-…`, `report-…`) and the report
+                  curation findings (`report-on-surface`,
+                  `index-is-not-a-report`). The message wording may change; the
+                  code does not.
               severity:
                 type: string
                 enum:
                   - error
                   - warn
                 description: >-
-                  Finding severity. Render-tag findings use both: `error` for
+                  Finding severity, `error` or `warn` and nothing else; a
+                  deprecated form that still loads (such as
+                  `deprecated-malloynb-notebook`) is `warn`. Render-tag findings use both: `error` for
                   a tag malformed for the field it sits on, which renders as
                   "[object Object]" or an inline error at query time, and `warn`
                   for one that is well-formed but inert where it sits and so is
@@ -3905,10 +4423,242 @@ components:
             - type: "null"
           readOnly: true
           description: >-
-            Server-computed, read-only: the state of this package's semantic
-            discovery index, which is what `get_context` ranks against
-            when an embedding provider is configured. `status: lexical` when
-            the server has no provider, because there is no index to describe.
+            Server-computed, read-only: the state of this package's semantic
+            discovery index, which is what `get_context` ranks against
+            when an embedding provider is configured. `status: lexical` when
+            the server has no provider, because there is no index to describe.
+        servedRevision:
+          type: string
+          readOnly: true
+          description: >-
+            Server-computed, read-only: an identifier for the load that produced
+            what this package is currently serving. Minted fresh per load, so
+            two loads of byte-identical files carry different revisions. Use it
+            to tell one load from another, NOT to tell whether content changed:
+            it moves on every reload regardless. `sourceContentSha` answers that.
+        sourceContentSha:
+          type: string
+          readOnly: true
+          description: >-
+            Server-computed, read-only: SHA-256 over the package-relative path
+            and bytes of every file the package is serving: each model file,
+            each package skill file under `skills/`, and, when the manifest
+            declares `agents`, the canonical form of that `agents` object plus
+            every instructions, task and skill file those agents read.
+
+            This is the reload receipt. Publisher serves a COPY of a package
+            under `publisher_data/<env>/<pkg>/` unless the environment was
+            started with `--watch-env`, so an edit to the original source
+            directory reaches nothing and the reload still reports success.
+            Comparing this value across a reload is what distinguishes "the
+            server recompiled my edit" from "the server recompiled the same
+            bytes it already had".
+
+            It covers EVERY model path in the package, so an edit to an imported
+            file moves it where a hash of one model path would not. It covers
+            nothing outside the list above: a data file, a `public/` asset, a
+            `version` bump or any other key in publisher.json (`retrieval`,
+            `explores`, `queryableSources`, `scope`) all leave it unchanged,
+            although some of those do change what is served. An unchanged value
+            therefore proves an edit to a hashed file did not reach the served
+            copy, and says nothing about an edit to anything else.
+        agents:
+          type: array
+          readOnly: true
+          description: >-
+            Server-computed, read-only: the agents this package's
+            `publisher.json` declares and the server accepted, without their
+            instructions. Absent when the manifest declares no `agents`. An
+            agent that failed validation is left out and named in `warnings`.
+            Fetch one with `GET .../agents/{agentName}`.
+          items:
+            $ref: "#/components/schemas/AgentSummary"
+
+    AgentSchedule:
+      type: object
+      readOnly: true
+      description: >-
+        A cron schedule an agent declares. Validated and exposed only: the
+        server never runs it.
+      properties:
+        cron:
+          type: string
+          description: A 5-field UNIX cron expression, evaluated in UTC.
+        task:
+          type: string
+          description: Package-relative path of the task file, as written in the manifest.
+        taskContent:
+          type: string
+          description: >-
+            The task file's Markdown. Only on the resolved agent, not the
+            listing.
+
+    AgentSummary:
+      type: object
+      readOnly: true
+      description: One agent a package declares, without its instructions or skills.
+      properties:
+        name:
+          type: string
+          description: The agent's name (its key in the manifest's `agents` object).
+        description:
+          type: string
+        model:
+          type: string
+          description: The model the agent asks for; `inherit` when the manifest sets none.
+        schedules:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentSchedule"
+
+    AgentSkillFile:
+      type: object
+      readOnly: true
+      description: >-
+        One of an agent's skill files. The snake_case keys
+        (`relative_filepath`, `file_contents`) mirror the MCP `get_agent` tool
+        the shape is shared with, unlike the camelCase used elsewhere in this
+        API.
+      properties:
+        relative_filepath:
+          type: string
+          description: >-
+            Path relative to the agent's skills directory, for example
+            `analyst-conventions/SKILL.md` or
+            `analyst-conventions/reference/glossary.md`.
+        file_contents:
+          type: string
+          description: >-
+            A `SKILL.md` is re-emitted with only a quoted `name` and
+            `description` in its frontmatter; reference files are served raw.
+            Absent when the agent was fetched with `skills=summary`.
+        name:
+          type: string
+          description: A `SKILL.md`'s name. Only in the `skills=summary` view.
+        description:
+          type: string
+          description: A `SKILL.md`'s description. Only in the `skills=summary` view.
+        bytes:
+          type: integer
+          description: Size of `file_contents` in UTF-8 bytes. Only in the `skills=summary` view.
+
+    AgentSkillRead:
+      type: object
+      readOnly: true
+      description: One agent skill file, with the pin of the definition it belongs to.
+      properties:
+        relative_filepath:
+          type: string
+        file_contents:
+          type: string
+        source:
+          $ref: "#/components/schemas/AgentSource"
+
+    AgentSource:
+      type: object
+      readOnly: true
+      description: What a resolved agent was read from, so a runner can prove which bytes ran.
+      properties:
+        environment:
+          type: string
+        package:
+          type: string
+        sourceContentSha:
+          type: string
+          description: The package's `sourceContentSha` at the load this definition came from.
+        definitionSha:
+          type: string
+          description: >-
+            SHA-256 over this agent's canonical config, instructions, skill
+            files and task files. Editing another agent, or a model, does not
+            move it.
+        servedRevision:
+          type: string
+          description: The package's `servedRevision` at the load this definition came from.
+
+    Agent:
+      type: object
+      readOnly: true
+      description: >-
+        An agent a package declares, resolved to its instructions, skill files
+        and schedules. Adopt it only when the user asks for it by name.
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        model:
+          type: string
+          description: The model the agent asks for; `inherit` when the manifest sets none.
+        instructions:
+          type: string
+          description: The instructions file's Markdown, at most 16 KB.
+        skills:
+          type: array
+          description: The agent's own skill files, sorted by `relative_filepath`.
+          items:
+            $ref: "#/components/schemas/AgentSkillFile"
+        schedules:
+          type: array
+          items:
+            $ref: "#/components/schemas/AgentSchedule"
+        warnings:
+          type: array
+          items:
+            type: string
+        source:
+          $ref: "#/components/schemas/AgentSource"
+
+    SkillSummary:
+      type: object
+      readOnly: true
+      description: >-
+        One agent skill in force for a package, without its body. This is what
+        a caller reads to decide which skill to fetch.
+      properties:
+        name:
+          type: string
+          description: >-
+            The skill's name, and the identifier for fetching it. A name
+            containing a slash (`<skill>/<stem>`) is one skill's on-demand
+            reference file rather than a skill in its own right.
+        description:
+          type: string
+          description: >-
+            One line saying when to read this skill. Empty when the package
+            author omitted it, which is also reported as a package warning.
+        origin:
+          type: string
+          enum:
+            - bundled
+            - package
+          description: >-
+            `bundled` = shipped with this server. `package` = shipped by the
+            package under `skills/`, which includes a package skill whose name
+            matches a bundled one and therefore REPLACES it for this package.
+            Present so a caller can tell a replaced skill from the original,
+            which is otherwise invisible.
+
+    Skill:
+      type: object
+      readOnly: true
+      description: An agent skill with its full Markdown body.
+      properties:
+        name:
+          type: string
+          description: The skill's name.
+        description:
+          type: string
+          description: One line saying when to read this skill.
+        content:
+          type: string
+          description: The skill's full guidance, Markdown.
+        origin:
+          type: string
+          enum:
+            - bundled
+            - package
+          description: Where this skill came from. See SkillSummary.origin.
 
     PackageEmbeddingIndex:
       type: object
@@ -4170,35 +4920,350 @@ components:
             Declared query-time behavior when the freshness window is missed:
             serve live, serve the stale table, or fail the query.
 
-    Model:
+    Model:
+      type: object
+      description: Malloy model metadata and status information
+      properties:
+        resource:
+          type: string
+          description: Resource path to the model
+        packageName:
+          type: string
+          description: Name of the package containing this model
+        path:
+          type: string
+          description: Relative path to the model file within its package directory
+        isHidden:
+          type: boolean
+          description: |
+            True for a file this route lists only because the request set
+            `includeHiddenFilesAndSources`: a file the package's `index.malloy` (or a
+            legacy `explores`) does not expose. False for every other file, so every
+            entry is false without that option. It says whether the file is hidden, not
+            whether a query can reach it: under `queryableSources: "all"` a hidden file
+            can still be queried.
+        error:
+          type: string
+          description: Error message if the model failed to compile or load
+
+    Report:
+      type: object
+      required: [resource, packageName, path, name, layout, title, editable]
+      description: |
+        One report in a package, as list-reports lists it: a `.malloy` file
+        whose model-level `## artifact` tag makes it one, wherever it lives
+        outside `public/`, or a `.malloynb`. See ReportManifest for the detail a viewer needs to render
+        one.
+      properties:
+        resource:
+          type: string
+          description: Resource path to the report (get-report)
+        packageName:
+          type: string
+          description: Name of the package containing this report
+        path:
+          type: string
+          description: >-
+            The report's path within its package, such as `sales/q3.malloy`.
+            Its identity, and the only thing that addresses it.
+        name:
+          type: string
+          description: >-
+            The file's basename without its extension. A display label only:
+            two reports in different directories may share it.
+        layout:
+          type: string
+          enum: [grid, linear]
+          description: >-
+            How its tiles are placed: `linear` top to bottom, one column, or
+            `grid` by `columns`, `colspan` and `break`. Decided by its tags (see
+            list-reports), never by where the file lives.
+        title:
+          type: string
+          description: >-
+            Human title: the artifact tag's `title`, else the first line of the
+            `"` notes above the tag, else,
+            for a linear report, its first markdown heading, else `name`.
+        description:
+          type: string
+          description: The report's doc comment, when it has one.
+        editable:
+          type: boolean
+          description: >-
+            Whether the builder opens it as it is: false for a `.malloynb` and
+            for a linear report written as `run:` cells.
+        error:
+          type: string
+          description: >-
+            Error message when the report failed to compile, or its cells could
+            not be read.
+
+    ReportManifest:
+      description: |
+        A `Report` plus what a viewer needs to draw it. A report written as
+        tiles, of either layout, carries `tiles`, `dashboardColumns`,
+        `startingGivens`, `autorun` and `givens`, whose tiles and suggest
+        queries run through `POST …/models/{path}/query` with `givens`. A
+        linear report written as `run:` cells, or a `.malloynb`, carries
+        `notebook` instead.
+      allOf:
+        - $ref: "#/components/schemas/Report"
+        - type: object
+          properties:
+            tiles:
+              type: array
+              description: >-
+                The report's tiles, each run as its own query (or shown as text),
+                in order. Absent on a `run:`-cell report.
+              items:
+                $ref: "#/components/schemas/ReportTile"
+            dashboardColumns:
+              type: integer
+              description: >-
+                Grid width, from the `# dashboard {columns=N}` tag beside the
+                artifact tag. 1 on a linear report. Absent means the viewer's
+                default.
+            startingGivens:
+              allOf:
+                - $ref: "#/components/schemas/EncodedGivenValues"
+              description: >-
+                Starting values for controls, from the artifact tag. URL
+                parameters override these.
+            autorun:
+              type: boolean
+              description: >-
+                False batches control changes behind an Apply button instead of
+                re-running on every change. Defaults to true.
+            givens:
+              type: array
+              description: >-
+                The control row: one entry per given the report's tiles run with
+                (less a given only a source's gate reads, which a host injects),
+                widened to every given the entry file surfaces when a tile cannot be
+                resolved (see `ReportTile.givenNames`). `default` is the value the
+                query endpoint takes, not the Malloy literal: a `filter<…>` given
+                declared `f'West'` publishes `West`.
+              items:
+                $ref: "#/components/schemas/Given"
+            notebook:
+              allOf:
+                - $ref: "#/components/schemas/ReportCells"
+              description: >-
+                For a linear report written as `run:` cells, or a `.malloynb`: its
+                cells and model. Run a `.malloy`
+                report's cell through the model query endpoint, its `text` as
+                `query`; a `.malloynb`'s with execute-notebook-cell. Absent on a
+                report written as tiles, and on a
+                report that failed to compile.
+
+    ReportTile:
+      type: object
+      description: >-
+        One tile of a report. A `query` tile (the default) runs a query; a
+        `text` tile shows markdown and runs nothing, so a caller that runs a
+        report's tiles skips the ones with `kind` `text`.
+      properties:
+        kind:
+          type: string
+          enum: [query, text]
+          description: >-
+            `query` runs `query` through the model query endpoint; `text` shows
+            `markdown`. Absent means `query`.
+        name:
+          type: string
+          description: >-
+            A text tile's name: the bare word in `tiles=[…]` and on its
+            `##|(markdown) name` block. Absent on a query tile.
+        markdown:
+          type: string
+          description: >-
+            A text tile's body, the text of its `##|(markdown) name` block
+            without the opener. Empty when the file has no such block. Absent on
+            a query tile.
+        query:
+          type: string
+          description: >-
+            Absent on a text tile. The run expression exactly as written in `tiles=[…]`, for example
+            "orders -> by_month". An EXPRESSION rather than a name, so it goes in
+            the `query` field of a `POST …/models/{path}/query` body, prefixed
+            with `run:`.
+        restricted:
+          type: boolean
+          description: >-
+            Set on a tile of a compiled document (`CompileResult.document`) whose
+            source the caller may not read. The tile carries its `query` and
+            nothing derived from the source: no `givenNames`, no layout tags.
+        givenNames:
+          type: array
+          items:
+            type: string
+          description: |
+            Names of the givens this tile's compiled query reads: through its
+            view, its source's `where:`, a joined source's `where:`, a
+            dimension or measure it uses, and its source's `#(authorize)` and
+            `#(access_filter)` gates. A control not listed does not change the
+            tile, which is what a viewer's "Doesn't respond to" chip says. It
+            also tells a caller which tiles a changed control needs to re-run;
+            running a tile with the dashboard's whole control row also works,
+            because an unreferenced given is ignored. Absent when discovery
+            could not resolve the tile (its expression neither compiles nor is
+            a plain `source -> view` or named query the static walk reads), in
+            which case send the whole control row. One such tile
+            widens `ReportManifest.givens` to every given the entry file
+            surfaces, rather than the union over the resolvable tiles, so that
+            the row actually contains the givens that tile filters by.
+        label:
+          type: string
+          description: >-
+            Heading for the tile, from a `# label` on the view or query it names.
+            Absent when it carries none, in which case a viewer derives one from
+            the run expression.
+        subtitle:
+          type: string
+          description:
+            Second line under the heading, from a `# subtitle` on the view or
+            query it names.
+        colspan:
+          type: integer
+          description: >-
+            Grid columns this tile spans, from a `# colspan=N` on the view or
+            query it names, or from `colspan=N` on a text tile's entry in
+            `tiles=[…]`. Clamped to `dashboardColumns` at render time. Absent
+            means one column.
+        break:
+          type: boolean
+          description: >-
+            Start a new grid row at this tile, from a `# break` on the view or
+            query it names, or from `break` on a text tile's entry in
+            `tiles=[…]`. Named for the tag, so every per-tile field on this
+            schema is spelled the way an author writes it. A generated client
+            escapes the attribute where the word is reserved (the Python client
+            exposes `break_`) while the wire key stays `break`.
+        borderless:
+          type: boolean
+          description: >-
+            Draw the result with no card around it, from a `# borderless` on the
+            view or query it names. Together with `label`, `subtitle`, `colspan`
+            and `break` this is the whole per-child tag set `@malloydata/render`
+            resolves for a `# dashboard` nest child, read the same way here so one
+            view presents identically as a tile and as a nest.
+
+    ReportCells:
+      type: object
+      description: >-
+        A linear report written as cells, or a `.malloynb`: its cells, unexecuted,
+        and its model.
+      properties:
+        type:
+          type: string
+          description: Always `notebook`. Distinguishes the payload from the
+            compiled-model shape returned by the model endpoint.
+        packageName:
+          type: string
+          description: Name of the package containing this notebook
+        modelPath:
+          type: string
+          description: Relative path to the notebook file within its package directory
+        format:
+          type: string
+          enum: ["malloynb", "malloy"]
+          description:
+            The file format the notebook is written in. `malloynb` is the
+            cell-separated format; `malloy` is a linear `.malloy` report (see
+            list-reports), wherever it lives, whose cells are
+            its statements and its floating `(markdown)` notes in file order.
+        malloyVersion:
+          type: string
+          description: Version of the Malloy compiler used to generate the notebook data
+        modelInfo:
+          type: string
+          description: JSON string containing model metadata and structure information
+        notebookCells:
+          type: array
+          description: Array of notebook cells containing raw markdown and code content
+          items:
+            $ref: "#/components/schemas/NotebookCell"
+        annotations:
+          type: array
+          description:
+            Array of file-level (##) annotations attached to the notebook. For
+            a `.malloy` notebook, every own note that is not a floating
+            `(markdown)` cell, in file order, each note once. A `"` or `(text)`
+            note below the `## artifact` tag is dropped and not listed.
+          items:
+            type: string
+        startingGivens:
+          allOf:
+            - $ref: "#/components/schemas/EncodedGivenValues"
+          description:
+            Starting values for the notebook's controls. A `.malloy` notebook
+            declares them in its artifact tag (`## artifact { givens { … } }`),
+            a `.malloynb` in its file-level tags (`## givens { … }`). URL
+            parameters override these, which is why the two share a shape.
+            Omitted when the notebook declares none.
+        autorun:
+          type: boolean
+          description:
+            False batches control changes behind an Apply button instead of
+            re-running on every change. Defaults to true. A `.malloy` notebook
+            reads it from its artifact tag (`## artifact { autorun=false }`), a
+            `.malloynb` from its file-level tags (`## autorun=false`). The same
+            flag, with the same default, that `DashboardManifest.autorun`
+            carries.
+        sources:
+          type: array
+          description: Sources defined in the notebook's model
+          items:
+            $ref: "#/components/schemas/Source"
+        queries:
+          type: array
+          description: Named queries defined in the notebook's model
+          items:
+            $ref: "#/components/schemas/Query"
+
+    DataApp:
       type: object
-      description: Malloy model metadata and status information
+      description:
+        An in-package HTML data app within a Malloy package - a static page
+        served from the package's public/ directory
       properties:
         resource:
           type: string
-          description: Resource path to the model
+          description:
+            Canonical URL to the served data app. Root-relative and does
+            NOT carry the /api/v0 prefix, because a data app is a static asset
+            served off the server root rather than an API resource.
         packageName:
           type: string
-          description: Name of the package containing this model
+          description: Name of the package containing this data app
         path:
           type: string
-          description: Relative path to the model file within its package directory
-        isHidden:
-          type: boolean
-          description: |
-            True for a file this route lists only because the request set
-            `includeHiddenFilesAndSources`: a file the package's `index.malloy` (or a
-            legacy `explores`) does not expose. False for every other file, so every
-            entry is false without that option. It says whether the file is hidden, not
-            whether a query can reach it: under `queryableSources: "all"` a hidden file
-            can still be queried.
-        error:
+          description: Relative path to the HTML file within its package directory
+        title:
           type: string
-          description: Error message if the model failed to compile or load
+          description:
+            Title extracted from the file's <title> tag, or the path if
+            not present
+        fit:
+          type: string
+          enum:
+            - viewport
+          description:
+            Layout hint read from a <meta name="publisher:fit"> tag in the
+            page <head>. "viewport" tells the embedded viewer to fill the
+            available height instead of auto-sizing to the content height, for
+            full-screen apps like slide decks. Omitted for an ordinary
+            content-driven app, which keeps content-height auto-sizing.
+
+    # ── DEPRECATED ────────────────────────────────────────────────────────
+    # The shapes of the deprecated `…/dashboards*` and `…/notebooks*` routes.
+    # No report schema references them; each removal deletes its block here.
 
     Notebook:
       type: object
-      description: Malloy notebook metadata and status information
+      deprecated: true
+      description: DEPRECATED, use `Report`. A linear report as the deprecated
+        list-notebooks route lists it.
       properties:
         environmentName:
           type: string
@@ -4230,10 +5295,10 @@ components:
 
     Dashboard:
       type: object
+      deprecated: true
       description: |
-        A dashboard within a Malloy package: a self-contained `.malloy` file at
-        the top of the package's `dashboards/` or `notebooks/` directory carrying an `# artifact` (or
-        model-level `## artifact`) annotation. The list entry; see
+        DEPRECATED: use `Report`. A grid report (see list-reports), as the
+        deprecated list-dashboards route lists it. The list entry; see
         DashboardManifest for the detail a viewer needs to render one.
       properties:
         resource:
@@ -4244,14 +5309,17 @@ components:
           description: Name of the package containing this dashboard
         name:
           type: string
-          description:
-            The dashboard's slug — its filename basename. Addresses it in a URL
-            and as a `# drill` target.
+          description: >-
+            The report's filename basename: a display label, and the segment of
+            the deprecated get-dashboard URL. Not an identity: two reports may
+            share it. A change since reports: it used to be unique within the
+            package (every dashboard was directly under `dashboards/`), and a
+            client that keyed a map on it must key on `path` instead.
         path:
           type: string
           description:
-            Relative path to the dashboard file within its package directory
-            (`dashboards/<name>.malloy`)
+            Relative path to the report file within its package directory,
+            which is its identity
         title:
           type: string
           description:
@@ -4269,7 +5337,9 @@ components:
 
     DashboardManifest:
       type: object
+      deprecated: true
       description: |
+        DEPRECATED: use `ReportManifest`.
         Everything a viewer needs to render one dashboard: the artifact tag's
         declarations plus the control contract derived from the givens its query
         references. Running needs no dashboard-specific endpoint — the query,
@@ -4284,14 +5354,17 @@ components:
           description: Name of the package containing this dashboard
         name:
           type: string
-          description:
-            The dashboard's slug — its filename basename. Addresses it in a URL
-            and as a `# drill` target.
+          description: >-
+            The report's filename basename: a display label, and the segment of
+            the deprecated get-dashboard URL. Not an identity: two reports may
+            share it. A change since reports: it used to be unique within the
+            package (every dashboard was directly under `dashboards/`), and a
+            client that keyed a map on it must key on `path` instead.
         path:
           type: string
           description: |
-            Relative path to the dashboard file within its package directory
-            (`dashboards/<name>.malloy`). This is also the model to POST to:
+            Relative path to the report file within its package directory,
+            which is its identity. This is also the model to POST to:
             `query`, each tile, and each control's suggest query all run through
             `POST /environments/{environmentName}/packages/{packageName}/models/{path}/query`
             with `givens`, which is why there is no dashboard-specific run
@@ -4310,32 +5383,27 @@ components:
         error:
           type: string
           description: Error message if the dashboard file failed to compile
-        kind:
+        layout:
           type: string
-          enum: [dashboard, notebook]
+          enum: [grid, linear]
           description: >-
-            What the document is, from the `kind` property of its artifact tag
-            (the folder only decides the default when the tag says nothing). A
-            `notebook` is laid out as one column: `dashboardColumns` is 1
-            whatever the file says. Always `dashboard` on
-            `GET …/dashboards/{dashboardName}`; a notebook's manifest is the
-            `dashboard` field of `GET …/notebooks/{path}`.
-        query:
+            The report's layout (see list-reports). A `linear` report is laid
+            out as one column: `dashboardColumns` is 1 whatever the file says.
+        kind:
           type: string
+          enum: [dashboard, notebook]
+          deprecated: true
           description: >-
-            Name of the tagged query whose single result IS the page. Set when the
-            `# artifact` tag sits on a `query:`; a dashboard authored the ordinary
-            way carries `tiles` instead and leaves this absent. A NAME rather than
-            an expression, so it goes in the `queryName` field of a
-            `POST …/models/{path}/query` body. A tile's `query` is the other shape
-            and is not interchangeable with this one; see `DashboardTile.query`.
+            DEPRECATED: read `layout`. The same thing in the old vocabulary:
+            `dashboard` for a grid report, `notebook` for a linear one. Always
+            `dashboard` on `GET …/dashboards/{dashboardName}`; a linear
+            report's manifest is the `dashboard` field of
+            `GET …/notebooks/{path}`.
         tiles:
           type: array
           description: >-
             The dashboard's tiles, each run as its own query and combined into one
-            grid. This is how a dashboard is normally authored, and the only form
-            that can span sources. Absent when the `# artifact` tag sits on a
-            `query:` instead, in which case `query` is set.
+            grid. Absent on a dashboard listed with its compile `error`.
           items:
             $ref: "#/components/schemas/DashboardTile"
         dashboardColumns:
@@ -4391,213 +5459,32 @@ components:
             $ref: "#/components/schemas/Given"
 
     DashboardTile:
-      type: object
+      deprecated: true
       description: >-
-        One tile of a dashboard. A `query` tile (the default) runs a query; a
-        `text` tile shows markdown and runs nothing, so a caller that runs a
-        dashboard's tiles skips the ones with `kind` `text`.
-      properties:
-        kind:
-          type: string
-          enum: [query, text]
-          description: >-
-            `query` runs `query` through the model query endpoint; `text` shows
-            `markdown`. Absent means `query`.
-        name:
-          type: string
-          description: >-
-            A text tile's name: the bare word in `tiles=[…]` and on its
-            `##|(markdown) name` block. Absent on a query tile.
-        markdown:
-          type: string
-          description: >-
-            A text tile's body, the text of its `##|(markdown) name` block
-            without the opener. Empty when the file has no such block. Absent on
-            a query tile.
-        query:
-          type: string
-          description: >-
-            Absent on a text tile. The run expression exactly as written in `tiles=[…]`, for example
-            "orders -> by_month". An EXPRESSION rather than a name, so it goes in
-            the `query` field of a `POST …/models/{path}/query` body, prefixed
-            with `run:`. Sending it in `queryName`, the field
-            `DashboardManifest.query` takes, is rejected.
-        restricted:
-          type: boolean
-          description: >-
-            Set on a tile of a compiled document (`CompileResult.document`) whose
-            source the caller may not read. The tile carries its `query` and
-            nothing derived from the source: no `givenNames`, no layout tags.
-        givenNames:
-          type: array
-          items:
-            type: string
-          description: |
-            Names of the givens this tile's compiled query reads: through its
-            view, its source's `where:`, a joined source's `where:`, a
-            dimension or measure it uses, and its source's `#(authorize)` and
-            `#(access_filter)` gates. A control not listed does not change the
-            tile, which is what a viewer's "Doesn't respond to" chip says. It
-            also tells a caller which tiles a changed control needs to re-run;
-            running a tile with the dashboard's whole control row also works,
-            because an unreferenced given is ignored. Absent when discovery
-            could not resolve the tile (its expression neither compiles nor is
-            a plain `source -> view` or named query the static walk reads), in
-            which case send the whole control row. One such tile
-            widens `DashboardManifest.givens` to every given the entry file
-            surfaces, rather than the union over the resolvable tiles, so that
-            the row actually contains the givens that tile filters by.
-        label:
-          type: string
-          description: >-
-            Heading for the tile, from a `# label` on the view or query it names.
-            Absent when it carries none, in which case a viewer derives one from
-            the run expression.
-        subtitle:
-          type: string
-          description:
-            Second line under the heading, from a `# subtitle` on the view or
-            query it names.
-        colspan:
-          type: integer
-          description: >-
-            Grid columns this tile spans, from a `# colspan=N` on the view or
-            query it names, or from `colspan=N` on a text tile's entry in
-            `tiles=[…]`. Clamped to `dashboardColumns` at render time. Absent
-            means one column.
-        break:
-          type: boolean
-          description: >-
-            Start a new grid row at this tile, from a `# break` on the view or
-            query it names, or from `break` on a text tile's entry in
-            `tiles=[…]`. Named for the tag, so every per-tile field on this
-            schema is spelled the way an author writes it. A generated client
-            escapes the attribute where the word is reserved (the Python client
-            exposes `break_`) while the wire key stays `break`.
-        borderless:
-          type: boolean
-          description: >-
-            Draw the result with no card around it, from a `# borderless` on the
-            view or query it names. Together with `label`, `subtitle`, `colspan`
-            and `break` this is the whole per-child tag set `@malloydata/render`
-            resolves for a `# dashboard` nest child, read the same way here so one
-            view presents identically as a tile and as a nest.
-
-    DataApp:
-      type: object
-      description:
-        An in-package HTML data app within a Malloy package - a static page
-        served from the package's public/ directory
-      properties:
-        resource:
-          type: string
-          description:
-            Canonical URL to the served data app. Root-relative and does
-            NOT carry the /api/v0 prefix, because a data app is a static asset
-            served off the server root rather than an API resource.
-        packageName:
-          type: string
-          description: Name of the package containing this data app
-        path:
-          type: string
-          description: Relative path to the HTML file within its package directory
-        title:
-          type: string
-          description:
-            Title extracted from the file's <title> tag, or the path if
-            not present
-        fit:
-          type: string
-          enum:
-            - viewport
-          description:
-            Layout hint read from a <meta name="publisher:fit"> tag in the
-            page <head>. "viewport" tells the embedded viewer to fill the
-            available height instead of auto-sizing to the content height, for
-            full-screen apps like slide decks. Omitted for an ordinary
-            content-driven app, which keeps content-height auto-sizing.
+        DEPRECATED: `ReportTile`, under the name the deprecated dashboard
+        routes gave it.
+      allOf:
+        - $ref: "#/components/schemas/ReportTile"
 
     RawNotebook:
-      type: object
-      description: Raw Malloy notebook with unexecuted cell contents
-      properties:
-        type:
-          type: string
-          description: Always `notebook`. Distinguishes the payload from the
-            compiled-model shape returned by the model endpoint.
-        packageName:
-          type: string
-          description: Name of the package containing this notebook
-        modelPath:
-          type: string
-          description: Relative path to the notebook file within its package directory
-        format:
-          type: string
-          enum: ["malloynb", "malloy"]
-          description:
-            The file format the notebook is written in. `malloynb` is the
-            cell-separated format; `malloy` is a `.malloy` at the top of `notebooks/` or
-            `dashboards/` whose model-level `## artifact` tag says `kind=notebook` (or names no
-            `kind` and sits under `notebooks/`), whose cells are
-            its statements and its floating `(markdown)` notes in file order.
-        malloyVersion:
-          type: string
-          description: Version of the Malloy compiler used to generate the notebook data
-        modelInfo:
-          type: string
-          description: JSON string containing model metadata and structure information
-        notebookCells:
-          type: array
-          description: Array of notebook cells containing raw markdown and code content
-          items:
-            $ref: "#/components/schemas/NotebookCell"
-        dashboard:
-          allOf:
-            - $ref: "#/components/schemas/DashboardManifest"
-          description: >-
-            The tile layout of a notebook written as one (`## artifact {
-            kind=notebook tiles=[…] }`), in the shape a dashboard has, with
-            `kind` `notebook` and one column. Absent on a notebook written as
-            cells. Its tiles run through the model query endpoint at
-            `modelPath`; `notebookCells` carries the same content as cells for
-            readers that do not draw a layout.
-        annotations:
-          type: array
-          description:
-            Array of file-level (##) annotations attached to the notebook. For
-            a `.malloy` notebook, every own note that is not a floating
-            `(markdown)` cell, in file order, each note once. A `"` or `(text)`
-            note below the `## artifact` tag is dropped and not listed.
-          items:
-            type: string
-        startingGivens:
-          allOf:
-            - $ref: "#/components/schemas/EncodedGivenValues"
-          description:
-            Starting values for the notebook's controls. A `.malloy` notebook
-            declares them in its artifact tag (`## artifact { givens { … } }`),
-            a `.malloynb` in its file-level tags (`## givens { … }`). URL
-            parameters override these, which is why the two share a shape.
-            Omitted when the notebook declares none.
-        autorun:
-          type: boolean
-          description:
-            False batches control changes behind an Apply button instead of
-            re-running on every change. Defaults to true. A `.malloy` notebook
-            reads it from its artifact tag (`## artifact { autorun=false }`), a
-            `.malloynb` from its file-level tags (`## autorun=false`). The same
-            flag, with the same default, that `DashboardManifest.autorun`
-            carries.
-        sources:
-          type: array
-          description: Sources defined in the notebook's model
-          items:
-            $ref: "#/components/schemas/Source"
-        queries:
-          type: array
-          description: Named queries defined in the notebook's model
-          items:
-            $ref: "#/components/schemas/Query"
+      deprecated: true
+      description: >-
+        DEPRECATED: `ReportCells`, as get-notebook answers them, plus the tile
+        layout of a linear report written as tiles.
+      allOf:
+        - $ref: "#/components/schemas/ReportCells"
+        - type: object
+          properties:
+            dashboard:
+              allOf:
+                - $ref: "#/components/schemas/DashboardManifest"
+              description: >-
+                The tile layout of a linear report written as one (`## artifact {
+                layout=linear tiles=[…] }`), in the shape a dashboard has, with
+                `layout` `linear` and one column. Absent on a notebook written as
+                cells. Its tiles run through the model query endpoint at
+                `modelPath`; `notebookCells` carries the same content as cells for
+                readers that do not draw a layout.
 
     CompiledModel:
       type: object
@@ -5792,8 +6679,7 @@ components:
           type: integer
           minimum: 1
           maximum: 2147483647
-          description:
-            Maximum run time of each statement on the database, in
+          description: Maximum run time of each statement on the database, in
             milliseconds. The database cancels a statement that exceeds it.
             When omitted, the database's own statement_timeout applies. Not
             applied to a DuckLake catalog connection.
@@ -5999,6 +6885,7 @@ components:
       required:
         - storage
         - catalog
+
     BigqueryConnection:
       type: object
       description: Google BigQuery database connection configuration
@@ -6216,6 +7103,7 @@ components:
         azureConnection:
           $ref: "#/components/schemas/AzureConnection"
     # TODO: What is this?  Can we remove it?
+
     SqlSource:
       type: object
       properties:
@@ -6538,13 +7426,20 @@ components:
         serves once saved. Present only when the source carries a model-level
         `## artifact` tag and compiled far enough to read.
       properties:
+        layout:
+          type: string
+          enum: [grid, linear]
+          description: >-
+            The report's layout, by the one rule every report follows: the
+            tag's `layout=`, else grid when it lists `tiles` or carries a
+            `dashboard { … }` grid tag, else linear.
         kind:
           type: string
           enum: [dashboard, notebook]
+          deprecated: true
           description: >-
-            From the tag's `kind`. When it names none, a document that lists
-            `tiles` or carries a `dashboard { … }` grid tag is a dashboard and
-            any other is a notebook: submitted text has no folder to decide.
+            DEPRECATED: read `layout`. The same thing in the old vocabulary:
+            `dashboard` for grid, `notebook` for linear.
         manifest:
           allOf:
             - $ref: "#/components/schemas/DashboardManifest"
@@ -6932,6 +7827,7 @@ components:
             The given names this term reads, in first-seen order. A reader must
             bind these for the term to apply; binding none applies each given's
             declared default, as a live query would.
+
     JoinedTerms:
       type: object
       required: [alias, source, terms]
@@ -6954,6 +7850,7 @@ components:
           description: >-
             The joined source's own stripped terms, which its binding re-applies
             with the caller's values.
+
     PersistSourcePlan:
       type: object
       required: [name, sourceID, connectionName, sourceEntityId, sql, columns]