daggerml 0.1.3__tar.gz → 0.1.4__tar.gz

daggerml-0.1.3/.github/workflows/pages.yml → daggerml-0.1.4/.github/workflows/docs.yml

@@ -1,13 +1,13 @@
-name: Documentation Pages
+name: Docs
 
 on:
   workflow_run:
-    workflows: [CI]
+    workflows: [Test]
     types: [completed]
-    branches: [master]
 
 permissions:
   contents: read
+  actions: read
 
 concurrency:
   group: documentation-pages
@@ -18,18 +18,36 @@ jobs:
     if: >-
       github.event.workflow_run.conclusion == 'success' &&
       github.event.workflow_run.event == 'push' &&
-      github.event.workflow_run.head_repository.full_name == github.repository
+      github.event.workflow_run.head_repository.full_name == github.repository &&
+      startsWith(github.event.workflow_run.head_branch, 'v')
     runs-on: ubuntu-latest
     permissions:
       contents: read
+      actions: read
     environment:
       name: github-pages
       url: https://daggerml.com/
     steps:
+      - name: Download tested release ref
+        uses: actions/download-artifact@v8
+        with:
+          name: release-ref-${{ github.event.workflow_run.run_attempt }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+          path: ${{ runner.temp }}/release
       - uses: actions/checkout@v6
         with:
           ref: ${{ github.event.workflow_run.head_sha }}
           fetch-depth: 0
+          fetch-tags: true
+      - name: Verify tested release tag
+        env:
+          TESTED_TAG: ${{ github.event.workflow_run.head_branch }}
+          TESTED_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          [[ "$TESTED_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          [[ "$(< "$RUNNER_TEMP/release/release-ref")" == "refs/tags/$TESTED_TAG" ]]
+          [[ "$(git rev-parse "refs/tags/$TESTED_TAG^{commit}")" == "$TESTED_SHA" ]]
       - uses: actions/setup-python@v6
         with:
           python-version: "3.13"

daggerml-0.1.4/.github/workflows/pypi.yml

@@ -0,0 +1,168 @@
+name: PyPI
+
+on:
+  workflow_run:
+    workflows: [Test]
+    types: [completed]
+
+permissions:
+  contents: read
+  actions: read
+
+jobs:
+  verify-tag:
+    if: >-
+      github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_repository.full_name == github.repository &&
+      startsWith(github.event.workflow_run.head_branch, 'v')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Download tested release ref
+        uses: actions/download-artifact@v8
+        with:
+          name: release-ref-${{ github.event.workflow_run.run_attempt }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+          path: ${{ runner.temp }}/release
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Verify tested release tag
+        env:
+          TESTED_TAG: ${{ github.event.workflow_run.head_branch }}
+          TESTED_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          [[ "$TESTED_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          [[ "$(< "$RUNNER_TEMP/release/release-ref")" == "refs/tags/$TESTED_TAG" ]]
+          [[ "$(git rev-parse "refs/tags/$TESTED_TAG^{commit}")" == "$TESTED_SHA" ]]
+  build-wheels:
+    needs: verify-tag
+    strategy:
+      fail-fast: false
+      matrix:
+        python:
+          - version: "3.11"
+            identifier: cp311
+          - version: "3.12"
+            identifier: cp312
+          - version: "3.13"
+            identifier: cp313
+          - version: "3.14"
+            identifier: cp314
+        platform:
+          - id: linux
+            os: ubuntu-latest
+          - id: macos
+            os: macos-latest
+    runs-on: ${{ matrix.platform.os }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Download verified dashboard assets
+        uses: actions/download-artifact@v8
+        with:
+          name: dashboard-assets-${{ github.event.workflow_run.run_attempt }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+          path: src/daggerml/dashboard/static/
+      - name: Build wheel
+        uses: pypa/cibuildwheel@v3.2.1
+        env:
+          CIBW_BUILD: "${{ matrix.python.identifier }}-*"
+          CIBW_ARCHS: auto
+          CIBW_TEST_EXTRAS: dashboard
+          CIBW_TEST_REQUIRES: httpx
+          CIBW_TEST_COMMAND: python -I {project}/tests/distribution/check_installed_docs.py
+      - name: Upload wheel
+        uses: actions/upload-artifact@v7
+        with:
+          name: wheel-${{ matrix.platform.id }}-${{ matrix.python.identifier }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+          retention-days: 2
+  build-sdist:
+    needs: verify-tag
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+          fetch-tags: true
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Download verified dashboard assets
+        uses: actions/download-artifact@v8
+        with:
+          name: dashboard-assets-${{ github.event.workflow_run.run_attempt }}
+          run-id: ${{ github.event.workflow_run.id }}
+          github-token: ${{ github.token }}
+          path: src/daggerml/dashboard/static/
+      - name: Build source distribution
+        run: |
+          pip install hatch
+          hatch build --target sdist
+      - name: Check installed sdist-derived wheel
+        run: |
+          python -m pip wheel --no-deps --wheel-dir "$RUNNER_TEMP/sdist-wheel" dist/*.tar.gz
+          python -m venv "$RUNNER_TEMP/sdist-docs"
+          "$RUNNER_TEMP/sdist-docs/bin/python" -m pip install "$RUNNER_TEMP"/sdist-wheel/*.whl
+          "$RUNNER_TEMP/sdist-docs/bin/python" -m pip install 'daggerml[dashboard]' httpx
+          "$RUNNER_TEMP/sdist-docs/bin/python" -I tests/distribution/check_installed_docs.py
+      - name: Upload source distribution
+        uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 2
+  publish:
+    needs: [verify-tag, build-wheels, build-sdist]
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+      - name: Download wheels
+        uses: actions/download-artifact@v8
+        with:
+          pattern: wheel-*
+          path: dist
+          merge-multiple: true
+      - name: Download source distribution
+        uses: actions/download-artifact@v8
+        with:
+          name: sdist
+          path: dist
+      - name: Cache pip
+        uses: actions/cache@v6
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-3.13-publish-${{ hashFiles('**/pyproject.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-3.13-
+            ${{ runner.os }}-pip-
+      - name: Install hatch
+        run: pip install hatch
+      - name: Publish distributions
+        env:
+          HATCH_INDEX_USER: __token__
+          HATCH_INDEX_AUTH: ${{ secrets.PYPI_TOKEN }}
+        run: hatch publish

daggerml-0.1.3/.github/workflows/ci.yml → daggerml-0.1.4/.github/workflows/test.yml

@@ -1,10 +1,6 @@
-name: CI
+name: Test
 on:
   push:
-    branches:
-      - "**"
-    tags:
-      - "v[0-9]+.[0-9]+.[0-9]+"
   pull_request:
 permissions:
   contents: read
@@ -149,139 +145,24 @@ jobs:
       - name: Dashboard Python tests
         run: uv run pytest -m 'dashboard and not docker and not ssh and not external' .
       - name: Upload verified dashboard assets
+        if: github.ref_type == 'tag' && startsWith(github.ref_name, 'v')
         uses: actions/upload-artifact@v7
         with:
-          name: dashboard-assets
+          name: dashboard-assets-${{ github.run_attempt }}
           path: src/daggerml/dashboard/static/
           if-no-files-found: error
-          retention-days: 1
-  build-wheels:
-    needs: dashboard
-    if: >-
-      github.event_name == 'pull_request' ||
-      startsWith(github.ref, 'refs/tags/v')
-    strategy:
-      fail-fast: false
-      matrix:
-        python:
-          - version: "3.11"
-            identifier: cp311
-          - version: "3.12"
-            identifier: cp312
-          - version: "3.13"
-            identifier: cp313
-          - version: "3.14"
-            identifier: cp314
-        platform:
-          - id: linux
-            os: ubuntu-latest
-          - id: macos
-            os: macos-latest
-    # name: Build Python ${{ matrix.python.version }} wheel for ${{ matrix.platform.id }}
-    runs-on: ${{ matrix.platform.os }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.13"
-      - name: Download verified dashboard assets
-        uses: actions/download-artifact@v8
-        with:
-          name: dashboard-assets
-          path: src/daggerml/dashboard/static/
-      - name: Build wheel
-        uses: pypa/cibuildwheel@v3.2.1
-        env:
-          CIBW_BUILD: "${{ matrix.python.identifier }}-*"
-          CIBW_ARCHS: auto
-          CIBW_TEST_EXTRAS: dashboard
-          CIBW_TEST_REQUIRES: httpx
-          CIBW_TEST_COMMAND: python -I {project}/tests/distribution/check_installed_docs.py
-      - name: Upload wheel
-        uses: actions/upload-artifact@v7
-        with:
-          name: wheel-${{ matrix.platform.id }}-${{ matrix.python.identifier }}
-          path: wheelhouse/*.whl
-          if-no-files-found: error
-          retention-days: 1
-  build-sdist:
-    needs: dashboard
-    if: >-
-      github.event_name == 'pull_request' ||
-      startsWith(github.ref, 'refs/tags/v')
+          retention-days: 2
+  release-ref:
+    needs: [test, lint, sanitize, ssh-lifecycle, docker-lifecycle, dashboard]
+    if: github.ref_type == 'tag' && startsWith(github.ref_name, 'v')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-          fetch-tags: true
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.13"
-      - name: Download verified dashboard assets
-        uses: actions/download-artifact@v8
-        with:
-          name: dashboard-assets
-          path: src/daggerml/dashboard/static/
-      - name: Build source distribution
-        run: |
-          pip install hatch
-          hatch build --target sdist
-      - name: Check installed sdist-derived wheel
-        run: |
-          python -m pip wheel --no-deps --wheel-dir "$RUNNER_TEMP/sdist-wheel" dist/*.tar.gz
-          python -m venv "$RUNNER_TEMP/sdist-docs"
-          "$RUNNER_TEMP/sdist-docs/bin/python" -m pip install "$RUNNER_TEMP"/sdist-wheel/*.whl
-          "$RUNNER_TEMP/sdist-docs/bin/python" -m pip install 'daggerml[dashboard]' httpx
-          "$RUNNER_TEMP/sdist-docs/bin/python" -I tests/distribution/check_installed_docs.py
-      - name: Upload source distribution
+      - name: Record the tested tag ref
+        run: printf '%s\n' "$GITHUB_REF" > "$RUNNER_TEMP/release-ref"
+      - name: Upload release ref
         uses: actions/upload-artifact@v7
         with:
-          name: sdist
-          path: dist/*.tar.gz
+          name: release-ref-${{ github.run_attempt }}
+          path: ${{ runner.temp }}/release-ref
           if-no-files-found: error
-          retention-days: 1
-  publish:
-    needs:
-      ["test", "lint", "sanitize", "ssh-lifecycle", "docker-lifecycle", "dashboard", "build-wheels", "build-sdist"]
-    if: startsWith(github.ref, 'refs/tags/v')
-    name: Upload release to PyPI
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - name: Set up Python
-        uses: actions/setup-python@v6
-        with:
-          python-version: "3.13"
-      - name: Download wheels
-        uses: actions/download-artifact@v8
-        with:
-          pattern: wheel-*
-          path: dist
-          merge-multiple: true
-      - name: Download source distribution
-        uses: actions/download-artifact@v8
-        with:
-          name: sdist
-          path: dist
-      - name: Cache pip
-        uses: actions/cache@v6
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-3.13-publish-${{ hashFiles('**/pyproject.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-3.13-
-            ${{ runner.os }}-pip-
-      - name: Install hatch
-        run: |
-          pip install hatch
-      - name: Publish distributions
-        env:
-          HATCH_INDEX_USER: __token__
-          HATCH_INDEX_AUTH: ${{ secrets.PYPI_TOKEN }}
-        run: hatch publish
+          retention-days: 2

{daggerml-0.1.3 → daggerml-0.1.4}/CONTRIBUTING.md

@@ -79,9 +79,11 @@ requests and appreciate your help in improving this project.
   ```
   uv run --dev --all-extras pytest -m "not slow" .
   ```
-- CI runs local/Moto deterministic coverage with `-m "not dashboard and not
-  docker and not ssh and not external"`; the dashboard job runs dashboard-marked
-  Python tests after building verified assets on pushes, pull requests, and tags.
+- The `Test` workflow runs on every push, as well as pull
+  requests. It runs local/Moto deterministic coverage with `-m "not dashboard and
+  not docker and not ssh and not external"`; the dashboard job runs
+  dashboard-marked Python tests after building verified assets. On release tags,
+  it retains those assets for two days for the `PyPI` workflow.
   Dedicated jobs run Docker and local-SSH coverage. Local quick loops use
   `-m "not slow"`.
 - We mark tests under `tests/_core/` with `@pytest.mark.core`. Core tests are included by default. You can select or skip them with:
@@ -120,25 +122,27 @@ requests and appreciate your help in improving this project.
   DOCS_PYTHON="/path/to/python" bash docs/build.sh
   ```
 - The build executes all QMD examples against disposable fixtures; do not use it as a substitute for the full test suite.
-- CI builds and verifies the dashboard and executable documentation once in the
-  Linux `dashboard` job, then runs dashboard Python tests against those assets.
-  Wheel and source-distribution jobs download its `dashboard-assets` artifact and
-  package those same verified files. macOS wheel runners therefore do not need
-  Docker or the documentation build toolchain.
+- `Test` builds and verifies the dashboard and executable documentation once in
+  the Linux `dashboard` job, then runs dashboard Python tests against those
+  assets. After a successful release-tag run, `PyPI` builds wheels and a source
+  distribution using the verified dashboard artifact from that exact Test run
+  and attempt. macOS wheel runners therefore do not need Docker or the
+  documentation build toolchain.
 
 ### GitHub Pages
 
-The separate `Documentation Pages` workflow runs after `CI` completes successfully
-for a push to `master`. It checks out the exact commit that passed CI, executes
-the documentation build, and replaces the entire organization website by publishing
+The `Docs` and `PyPI` workflows run after `Test` succeeds for a release-tag push.
+Both verify a tag-only release marker from the triggering Test run and check
+that the tag still points to the exact tested commit. `Docs` executes the
+documentation build and replaces the entire organization website by publishing
 to the root of `daggerml/daggerml.github.io`'s `gh-pages` branch. Stale website
 files are removed, and the `daggerml.com` custom domain is preserved.
-Pull requests, tags, other branches, and unsuccessful CI runs do not deploy.
+Pull requests, branch pushes, and unsuccessful Test runs do not deploy.
 The site URL is <https://daggerml.com/> (the organization Pages site).
-Configure `DOCS_PUBLISH_TOKEN` in this repository or its `github-pages` environment
-as a fine-grained token with **Contents: read and write** on
-`daggerml/daggerml.github.io`. The built-in `GITHUB_TOKEN` cannot publish to a
-different repository. In the destination repository's **Settings → Pages**, keep
+Configure `DOCS_DEPLOY_KEY` in this repository or its `github-pages` environment
+as a deploy key with write access to `daggerml/daggerml.github.io`. The built-in
+`GITHUB_TOKEN` cannot publish to a different repository. In the destination
+repository's **Settings → Pages**, keep
 the source set to **Deploy from a branch**, `gh-pages`, `/ (root)`.
 
 To generate the same standalone output locally:

{daggerml-0.1.3 → daggerml-0.1.4}/DOC_MAP.md

@@ -38,6 +38,18 @@ Use this file to identify which project docs to read before editing a code path,
   - `src/daggerml/README.md`
   - `docs/use/inspection.qmd`
 
+### Bundled agent skills
+
+- Match: `src/daggerml/_core/skills/**`, skill installation methods in `src/daggerml/_core/dml.py`
+- Read:
+  - `docs/start-here/get-started.qmd`
+  - `docs/start-here/dags.qmd`
+  - `docs/start-here/funks.qmd`
+  - `docs/start-here/dagclasses.qmd`
+  - `docs/use/inspection.qmd`
+  - `openspec/specs/bundled-agent-skills/spec.md`
+  - `openspec/specs/admin-cli-controls/spec.md`
+
 ### Core repository operations
 
 - Match: `src/daggerml/_core/commit.py`, `src/daggerml/_core/dag.py`, `src/daggerml/_core/head.py`, `src/daggerml/_core/index.py`

{daggerml-0.1.3 → daggerml-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: daggerml
-Version: 0.1.3
+Version: 0.1.4
 Summary: DaggerML
 Author-Email: DaggerML <engineering@daggerml.com>
 License: MIT

daggerml-0.1.4/docs/start-here/get-started.qmd

@@ -0,0 +1,31 @@
+---
+title: Get started
+engine: knitr
+depends-on: start-here
+---
+
+DaggerML turns research computations into reproducible, shareable building
+blocks. Share functions as well as results: run them on your own inputs without
+reconciling environments, and reuse completed work when inputs match. Each
+result retains its provenance, and its computation remains runnable as long as
+the infrastructure it needs exists.
+
+<!-- docs:pseudocode: reader installation command; the docs build must use the current repository environment rather than install a released package. -->
+```bash
+pip install daggerml
+```
+
+## Start a project
+
+```{bash}
+mkdir research-demo
+cd research-demo
+dml init
+```
+
+## Built-in agent skills
+
+DaggerML includes skills for agents to help author DAGs, query results, manage
+projects, and build extensions (see: `dml skills --help`).
+
+Continue with [DAGs](dags.qmd) to create and query a result.

daggerml-0.1.4/openspec/changes/archive/2026-09-24-install-focused-agent-skills/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-24

daggerml-0.1.4/openspec/changes/archive/2026-09-24-install-focused-agent-skills/design.md

@@ -0,0 +1,25 @@
+## Context
+
+`_SkillsNamespace` currently reads package resources and returns strings; the generated CLI serializes them to stdout. The same public methods are callable in Python. The package resources already contain frontmatter with default names. See proposal.md for motivation.
+
+## Goals / Non-Goals
+
+**Goals:** Keep method-driven CLI generation, install from package resources without a checkout, and preserve clear write diagnostics in both Python and CLI.
+
+**Non-Goals:** Tool-specific registration, uninstall, or merging arbitrary files into existing skill directories.
+
+## Decisions
+
+- Use a required positional `parent: str` and optional `name: str | None`, `overwrite: bool = False` on each of the four methods; the CLI generates the flags and the methods return a concise diagnostic string containing the path and UTF-8 byte count. This retains the established generated surface rather than adding bespoke argparse commands.
+- Share an installation helper that reads the bundled resource, validates a simple single-component slug for `name`, replaces only the frontmatter name, creates the parent, and writes `<parent>/<name>/SKILL.md`. An existing target directory is rejected unless `overwrite=True`; overwriting preserves unrelated files. Avoid replacing the directory wholesale.
+- Keep bundled default names as packaged and substitute only the frontmatter name when requested. Reject path escapes and symlink targets when creating or overwriting files. On a failed write, do not return a success diagnostic.
+- Expand guidance around practical workflows using the existing public docs as source of truth, removing the previous 1000-word/two-example limits where they obstruct useful explanations.
+- Bundle each resource as `skills/<kind>/SKILL.md`, mirroring the installed directory layout and allowing additional supporting resources later. Include the nested Markdown files in source distributions and keep the authoring example self-contained with a dagclass definition and `api.run()` call.
+- Put runnable examples in `skills/<kind>/examples/*.py` and let the skill document point to them relative to its installed directory. Recursively copy bundled skill files, preflight all destinations before overwriting, preserve unrelated files, and count the bytes written across the directory. Include example sources in both wheel and sdist.
+- Use Vega's 2,000-flight airline-delay sample for the runnable dagclass example. Stage the source as a URI, keep train/test cuts and pickled models in the remote artifact store, run data/ML steps in a Docker image containing Polars and scikit-learn, and select the best trial using the out-of-sample R² node. Exercise the same schema against a deterministic fixture in a Docker/Moto integration test, building a test-owned image instead of depending on an externally maintained tag.
+- Let the built-in Polars codec normalize returned train/test DataFrames to Parquet artifacts. Downstream funks read the codec-produced `s3://` URIs through Polars directly; when the worker runs against an S3-compatible endpoint, supply that endpoint to Polars explicitly. Keep S3Store only for the source JSON and pickled model.
+
+## Risks / Trade-offs
+
+- Existing stdout consumers break → Document migration to parent-directory installation and adjust contract tests.
+- Replacing user-edited files can destroy work → Require explicit `--overwrite` for any existing skill directory, preserve unrelated files, and refuse symlink targets.

daggerml-0.1.4/openspec/changes/archive/2026-09-24-install-focused-agent-skills/proposal.md

@@ -0,0 +1,24 @@
+## Why
+
+Focused agent guidance currently prints to stdout, leaving users to manually construct a skill directory and filename. Authoring and querying guidance also needs fuller workflows for agents working from an installed package.
+
+## What Changes
+
+- **BREAKING** Replace stdout exports with `dml skills <kind> <parent> [--name NAME] [--overwrite]`, installing `<parent>/<name>/SKILL.md` and returning a write diagnostic.
+- Keep the four focused skill commands; allow custom installation names and explicit replacement of existing installations.
+- Expand the authoring and querying skills with actionable examples and decision guidance.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `admin-cli-controls`: Change the generated skill commands from stdout export to directory installation.
+- `bundled-agent-skills`: Make authoring and querying guidance more complete and allow installed names to match chosen folder names.
+
+## Impact
+
+`src/daggerml/_core/dml.py`, bundled Markdown resources, generated CLI help, tests, and documentation/specs describing skill delivery. Existing stdout-redirection scripts must use the new destination argument.

daggerml-0.1.4/openspec/changes/archive/2026-09-24-install-focused-agent-skills/specs/admin-cli-controls/spec.md

@@ -0,0 +1,35 @@
+## MODIFIED Requirements
+
+### Requirement: Admin exports the bundled agent skill
+The generated CLI SHALL expose `dml skills querying`, `dml skills authoring`, `dml skills repository`, and `dml skills extensions`. Each command SHALL accept a required destination parent directory, an optional `--name` (defaulting to `daggerml-<kind>`), and an optional `--overwrite`. It SHALL install the corresponding bundled skill directory at `<parent>/<name>/`, including `SKILL.md` and supporting files, with frontmatter `name` matching the directory name, and return a diagnostic identifying the directory and total bytes written. It SHALL reject unsafe names, and SHALL fail without modifying an existing target unless `--overwrite` is passed. The CLI SHALL NOT expose `dml skills inspection`, `dml admin agent-skill`, or an `admin` namespace.
+
+#### Scenario: Install a focused skill
+- **WHEN** a user runs `dml skills authoring .opencode/skills`
+- **THEN** `.opencode/skills/daggerml-authoring/SKILL.md` contains the complete authoring skill
+- **AND** the command reports its directory and total amount written
+
+#### Scenario: Install authoring example
+- **WHEN** a user runs `dml skills authoring .opencode/skills`
+- **THEN** `.opencode/skills/daggerml-authoring/examples/dagclass.py` is installed alongside `SKILL.md`
+
+#### Scenario: Install with a custom name
+- **WHEN** a user runs `dml skills querying .agents/skills --name research-querying`
+- **THEN** `.agents/skills/research-querying/SKILL.md` has `name: research-querying` in its frontmatter
+
+#### Scenario: Existing target requires explicit replacement
+- **WHEN** a destination skill directory already exists and `--overwrite` is absent
+- **THEN** installation fails without modifying that directory
+- **WHEN** `--overwrite` is present
+- **THEN** its bundled files are replaced and unrelated contents of that directory are preserved
+
+#### Scenario: Invalid skill name
+- **WHEN** a name includes a path separator, traversal, or is not a valid skill directory name
+- **THEN** installation fails without writing outside the destination parent
+
+#### Scenario: Replaced inspection route is rejected
+- **WHEN** a user runs `dml skills inspection`
+- **THEN** command parsing fails because `inspection` is not a generated skill command
+
+#### Scenario: Removed administrative route is rejected
+- **WHEN** a user runs `dml admin agent-skill`
+- **THEN** command parsing fails because `admin` is not a generated CLI namespace

daggerml-0.1.4/openspec/changes/archive/2026-09-24-install-focused-agent-skills/specs/bundled-agent-skills/spec.md

@@ -0,0 +1,37 @@
+## MODIFIED Requirements
+
+### Requirement: DaggerML SHALL bundle four focused agent skills
+DaggerML SHALL bundle portable skill directories named `querying`, `authoring`, `repository`, and `extensions`, each containing a `SKILL.md` document and any supporting examples. Each document SHALL begin with YAML frontmatter naming the skill and describing its purpose, be independently useful when installed without the other skill documents or repository-local documentation, and support substituting a user-chosen installation name in its frontmatter. A skill MAY direct readers to installed source modules for deeper investigation.
+
+#### Scenario: A user installs one focused skill
+- **WHEN** a user installs one named bundled skill
+- **THEN** the installed document contains YAML frontmatter with its installed name
+- **AND** it does not include the other three skill documents or require repository-local documentation
+
+### Requirement: Authoring skill SHALL guide reproducible DAG construction
+The `authoring` skill SHALL cover DAG construction and explicit commit lifecycle; named data staging and retrieval; collection access; direct and staged function calls; importing committed results and named nodes; dagclass composition; script-worker source boundaries; helper injection; provenance-preserving node reuse; cache identity; and complex-data normalization through installed codecs or artifact storage. It SHALL provide practical, self-contained workflows for authoring, composing, and diagnosing script-backed DAGs. It SHALL direct agents to pass nodes, projections, required results, and function-call results directly into funks and graph structures instead of materializing them prematurely. It SHALL explain that `.value()` is for inspection or concrete Python computation and include an example that passes a node directly at the authoring boundary before materializing it inside a funk. It SHALL provide operational guidance without requiring repository-local documentation or examples.
+
+#### Scenario: An agent retrieves authoring guidance
+- **WHEN** an agent uses the `authoring` skill to write a script-backed DAG
+- **THEN** it is directed to preserve graph identity by passing graph objects directly between funks
+- **AND** it sees `.value()` used where worker-side Python computation requires concrete data
+- **AND** it is directed to make imports or helper source available to the worker
+- **AND** it is warned that cache reuse is based on staged runnable and normalized DaggerML input identity
+
+#### Scenario: An agent authors a dagclass
+- **WHEN** an agent uses the `authoring` skill to define a dagclass
+- **THEN** it finds an installed Python example that stages airline delays, returns Polars train/test DataFrames for codec normalization, trains and persists tree models, predicts and scores both cuts, and searches over parameter sets by out-of-sample R²
+- **AND** it can see how the dagclass retains parameter/objective pairs as nodes, prints the best parameters and score, and uses `.value()` only where Python computation needs concrete data
+
+### Requirement: Querying skill SHALL guide data extraction and graph traversal
+The `querying` skill SHALL cover locating and loading DAGs, distinguishing terminal results from named nodes, traversing nodes and read-only projections, materializing values, following nearest and rooted provenance, and capturing persisted function errors with their context. It SHALL provide actionable workflows for selecting data, interpreting graph state, and investigating failed results using Python or available CLI inspection commands. It SHALL explain committed, active, and frozen graph-state distinctions necessary to read available data without turning into a repository-control or cache-management guide. It SHALL provide operational guidance without requiring repository-local documentation or examples.
+
+#### Scenario: An agent queries a completed DAG
+- **WHEN** an agent needs data from a committed DAG
+- **THEN** it is directed to select the terminal result or a named node deliberately
+- **AND** it can traverse nested data through projections before materializing the selected value
+
+#### Scenario: An agent encounters persisted failure data
+- **WHEN** node lookup or materialization encounters a persisted function error
+- **THEN** the skill directs the agent to retain the error origin, type, message, stack, and producing context
+- **AND** the failure is not treated as absent data