surf-agentic-base 0.3.0__tar.gz

surf_agentic_base-0.3.0/.dockerignore

@@ -0,0 +1,13 @@
+Dockerfile
+**/.git
+**/.gitignore
+**/.gitmodules
+**/.coverage
+**/venv
+**/.venv
+**/.idea
+**/.DS_Store
+**/__pycache__
+**/.mypy_cache
+**/.pytest_cache
+**/.ruff_cache

surf_agentic_base-0.3.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Review requests route here. Kept to the maintainer while the repository has one.
+* @saradamian

surf_agentic_base-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,29 @@
+name: Bug report
+description: Something behaves differently from what its documentation or its tests say.
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what should have happened
+      description: The observed behaviour and the expected one. Quote the assertion or the documented claim it contradicts.
+    validations: { required: true }
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: The smallest input that shows it. A failing test is the best form.
+      render: python
+    validations: { required: true }
+  - type: input
+    id: version
+    attributes:
+      label: Version and Python
+      placeholder: "surf-agentic-base 0.1.0, Python 3.10.12"
+    validations: { required: true }
+  - type: checkboxes
+    id: warnings
+    attributes:
+      label: Verification
+      options:
+        - label: I ran the suite without `-W ignore`.

surf_agentic_base-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security report
+    url: https://github.com/saradamian/agentic-base/security/advisories/new
+    about: Report a vulnerability privately. Do not open a public issue for it.

surf_agentic_base-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,20 @@
+name: Feature request
+description: Something the base layer should carry, with the consumer that needs it.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: consumer
+    attributes:
+      label: Which consumer needs this, and what does it do today instead
+      description: A base layer only carries what more than one consumer would otherwise write separately. Name the consumer.
+    validations: { required: true }
+  - type: textarea
+    id: existing
+    attributes:
+      label: What already exists that does this
+      description: Reuse, then buy, then build. Say what was checked and why it does not fit, or say nothing was found.
+    validations: { required: true }
+  - type: textarea
+    id: shape
+    attributes:
+      label: Proposed shape

surf_agentic_base-0.3.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+## What changes, and what does not
+
+<!-- One behaviour per pull request. Say what is deliberately left for a follow-up. Do not oversell:
+     a reviewer who finds the claim broader than the diff stops trusting the rest. -->
+
+Closes #
+
+## How it was verified
+
+- [ ] `uv sync --group dev --extra service` then `ruff check`, `ruff format --check`, `mypy src tests`
+- [ ] `pytest tests -q` **with no `-W` flag**. The repository treats warnings as errors; a run that ignores them is not a run.
+- [ ] Any new guard was broken on purpose and seen to fail before it was trusted.
+
+## Portability
+
+- [ ] If a module in `tests/test_portable_surface.py` changed: it still imports on 3.10 with only the four library dependencies.
+- [ ] No site-specific value in code, chart defaults or the Dockerfile. Those belong in a deployment overlay.
+
+## Risk
+
+| Question | Answer (write N/A explicitly) |
+|---|---|
+| Schema or stored record changed? | |
+| Public interface changed? | |
+| New dependency? | |
+| Touches URL fetching, secrets, or code execution? | |

surf_agentic_base-0.3.0/.github/allowed_signers

@@ -0,0 +1,5 @@
+# Who may sign a release tag. `.github/workflows/release.yml` verifies the tag against this
+# file before it builds anything, so a tag signed by a key absent from here does not release.
+# Rotating a key means a commit, which is the point: the set of people who can cut a release
+# is reviewable. The principal must equal the tagger email, or the signature does not match.
+26249073+saradamian@users.noreply.github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEj+dDHYzSSo0LOhb8OzHcyAumQsrXnzkH2yYwlKEKud

surf_agentic_base-0.3.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+# Dependabot and Renovate split the work rather than both doing it. Dependabot owns security
+# alerts and their fixes, and the workflow actions, because it is native here. Renovate owns
+# ordinary version updates and lock-file maintenance, and its config disables the actions manager
+# so the two never open the same pull request.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule: { interval: weekly }
+    labels: [dependencies]

surf_agentic_base-0.3.0/.github/release.yml

@@ -0,0 +1,16 @@
+# How generated release notes are grouped. Labels are applied to pull requests; the conventional
+# commit prefix is what the pre-commit hook checks, the label is what the notes read.
+changelog:
+  categories:
+    - title: Breaking
+      labels: [breaking]
+    - title: Features
+      labels: [feat, enhancement]
+    - title: Fixes
+      labels: [fix, bug]
+    - title: Documentation
+      labels: [documentation]
+    - title: Dependencies
+      labels: [dependencies]
+    - title: Other
+      labels: ["*"]

surf_agentic_base-0.3.0/.github/renovate.json5

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": ["config:recommended", ":semanticCommits"],
+  "lockFileMaintenance": { "enabled": true, "schedule": ["before 6am on monday"] },
+  "enabledManagers": ["pep621", "pip_requirements"],
+  "labels": ["dependencies"],
+  "packageRules": [
+    { "matchUpdateTypes": ["patch"], "automerge": false }
+  ]
+}

surf_agentic_base-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+# The gate this repository declares, run on both ends of the supported range. 3.10 is not
+# decoration: it is the floor a consumer of this library runs on, and the portable-surface guards
+# mean nothing unless something executes them there.
+#
+# Actions are pinned to commit hashes, not tags. A tag can be moved; a hash cannot.
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.14"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - run: uv lock --check
+      - run: uv sync --python ${{ matrix.python }} --group dev --extra service --extra provenance
+      - run: .venv/bin/ruff check src tests
+      - run: .venv/bin/ruff format --check src tests
+      - run: .venv/bin/mypy src tests
+      - run: .venv/bin/pytest tests -q --cov=src --cov-report=term
+        env:
+          DATABASE_URL: sqlite:///./ci.db

surf_agentic_base-0.3.0/.github/workflows/label.yml

@@ -0,0 +1,89 @@
+# The release notes group by pull request label (`.github/release.yml`). Nothing ever applied one:
+# all fourteen labels existed, none of the first five pull requests carried any, so every entry
+# would have been filed under "Other" and the grouping config could not do the thing it describes.
+#
+# The input is the conventional-commit prefix the commit hook already enforces, which squash
+# merging puts on main as the commit subject. Deriving the label from the title keeps one source
+# of truth rather than adding a second one for humans to keep in step.
+#
+# A prefix that maps to nothing is not an error. `chore`, `ci`, `test` and `refactor` belong under
+# "Other", and this says so rather than failing.
+#
+# The derivation RECONCILES rather than adds. A title edited from `feat:` to `fix:` re-fires this
+# workflow, and an add-only version would leave both labels in place; the notes then file the
+# entry under whichever category matches first, which is the stale one. So each label this
+# workflow can derive is either applied or removed on every run, and only those: a label a person
+# added by hand, `enhancement` or `good first issue`, is never touched.
+#
+# `pull_request_target` is used because a fork's `pull_request` token cannot write labels. It runs
+# with a writable token against the BASE repository, so this workflow deliberately checks out no
+# code at all and reads the title through the environment rather than interpolating it into the
+# script. Nothing from a fork is executed here.
+name: label
+
+on:
+  pull_request_target:
+    types: [opened, edited, reopened]
+
+permissions:
+  pull-requests: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: derive the grouping label from the conventional-commit prefix
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TITLE: ${{ github.event.pull_request.title }}
+          NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          prefix=${TITLE%%:*}
+
+          breaking=""
+          case "$prefix" in *'!') breaking="breaking" ;; esac
+          prefix=${prefix%!}
+          prefix=${prefix%%(*}
+
+          case "$prefix" in
+            feat)       label="feat" ;;
+            fix)        label="fix" ;;
+            docs)       label="documentation" ;;
+            deps|build) label="dependencies" ;;
+            *)          label="" ;;
+          esac
+
+          wanted=""
+          [ -n "$label" ] && wanted="$label"
+          [ -n "$breaking" ] && wanted="$wanted $breaking"
+
+          if [ -z "$wanted" ]; then
+            echo "prefix '$prefix' derives no grouping label; the notes file this under Other"
+          fi
+
+          # Everything this workflow is allowed to decide. A label outside this set belongs to
+          # whoever put it there. There is no early exit above: an empty derivation still has to
+          # REMOVE a label an earlier title produced.
+          managed="breaking dependencies documentation feat fix"
+          held=" $(gh api "repos/$REPO/issues/$NUMBER/labels" --jq '.[].name' | tr '\n' ' ')"
+
+          for name in $managed; do
+            case " $wanted " in *" $name "*) want=1 ;; *) want=0 ;; esac
+            case "$held"     in *" $name "*) have=1 ;; *) have=0 ;; esac
+
+            if [ "$want" = 1 ] && [ "$have" = 0 ]; then
+              # A JSON body on stdin, not `-f 'labels[]=x'`: that form is not understood by
+              # every gh version and 422s where it is not, failing this step for a reason that
+              # has nothing to do with the label.
+              printf '{"labels":["%s"]}' "$name" |
+                gh api "repos/$REPO/issues/$NUMBER/labels" --input - --silent
+              echo "added $name"
+            elif [ "$want" = 0 ] && [ "$have" = 1 ]; then
+              gh api -X DELETE "repos/$REPO/issues/$NUMBER/labels/$name" --silent
+              echo "removed $name, which the title no longer derives"
+            fi
+          done
+
+          set -- $managed
+          echo "reconciled $# derivable labels against the title"

surf_agentic_base-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,88 @@
+# A tag `vX.Y.Z` on main produces a release. The version inside the built distribution comes
+# from that same tag through setuptools-scm, so the two cannot disagree. Nothing is published to
+# a package index from here; that is a separate decision with its own owner.
+#
+# Three things a consumer of a release can check now, and could not before:
+#
+#   * the tag carries a signature from a key listed in `.github/allowed_signers`. Note that
+#     `gh release create --verify-tag`, at the end of this file, does NOT do this. It asserts the
+#     tag exists on the remote and reads no signature at all; the name invites the opposite
+#     reading. The rule starts at the next tag, because `v0.1.0` predates commit signing and the
+#     tag ruleset makes it immutable, so nobody can quietly re-sign it and close the gap;
+#   * the artifact installs and imports on the consumer's Python floor. The suite reads `src/`,
+#     so it cannot see a defect that exists only in the built wheel;
+#   * the artifact carries build provenance. Without it the chain of custody stops at the tag,
+#     and anyone with write access can replace a release asset with nothing to detect it.
+name: release
+
+on:
+  push:
+    tags: ["v*.*.*"]
+
+permissions:
+  contents: write
+  # `attest-build-provenance` mints a short-lived signing certificate for this run and writes the
+  # attestation back to the repository. Both are required. With `contents: write` alone the build
+  # succeeds and the attest step fails at the end of it, having spent the whole job first.
+  id-token: write
+  attestations: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          # The tag OBJECT, not just the commit it points at: the signature lives on the object.
+          fetch-tags: true
+
+      - name: the tag must be signed by a listed signer
+        run: |
+          git config gpg.ssh.allowedSignersFile .github/allowed_signers
+          git verify-tag "${GITHUB_REF_NAME}"
+
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - run: uv build
+
+      - name: the built version must equal the tag
+        run: |
+          built=$(ls dist/*.tar.gz | sed -E 's|.*/surf_agentic_base-(.*)\.tar\.gz|\1|')
+          test "v$built" = "${GITHUB_REF_NAME}" || { echo "built $built, tag ${GITHUB_REF_NAME}"; exit 1; }
+
+      - name: the wheel must install and import on the consumer floor
+        run: |
+          uv venv --python 3.10 /tmp/floor
+          uv pip install --python /tmp/floor/bin/python --quiet dist/*.whl
+          python3 scripts/check_wheel_imports.py /tmp/floor/bin/python
+
+      - uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-path: dist/*
+
+      - run: gh release create "${GITHUB_REF_NAME}" dist/* --generate-notes --verify-tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  # Trusted publishing: no token stored anywhere, PyPI accepts this workflow's OIDC identity
+  # for the project `surf-agentic-base` once that publisher is registered on pypi.org. A
+  # separate job so a publish failure is a red job on a release that already exists, never a
+  # release that silently does not.
+  publish:
+    needs: release
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - run: uv build
+      - name: the built version must equal the tag, here too
+        run: |
+          built=$(ls dist/*.tar.gz | sed -E 's|.*/surf_agentic_base-(.*)\.tar\.gz|\1|')
+          test "v$built" = "${GITHUB_REF_NAME}" || { echo "built $built, tag ${GITHUB_REF_NAME}"; exit 1; }
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

surf_agentic_base-0.3.0/.gitignore

@@ -0,0 +1,73 @@
+# Python
+venv
+.venv
+coverage.xml
+.coverage
+__pycache__/
+.mypy_cache
+.dmypy.json
+.ruff_cache
+.pytest_cache
+test-results.xml
+gl-code-quality-report.json
+gl-code-quality-report-ruff.json
+*.egg-info
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+.idea/**/*.iml
+.idea/**/misc.xml
+.idea/**/modules.xml
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# IntelliJ
+out/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# mkdocs
+site
+
+# Local databases. The service defaults to `sqlite:///./agentic-base.db` and the pipeline uses
+# `./ci.db`, so both land in the working directory. The only `.db` entries here were Windows
+# thumbnail caches by exact name, which meant a local run followed by `git add -A` could commit
+# a database. Names, not just the two we happen to create today.
+*.db
+*.db-wal
+*.db-shm
+*.sqlite
+*.sqlite3

surf_agentic_base-0.3.0/.markdownlint-cli2.jsonc

@@ -0,0 +1,7 @@
+// Rules can be found at: https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md
+{
+  "config": {
+    // MD013 - Line length | https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md#md013---line-length
+    "MD013": false
+  }
+}

surf_agentic_base-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,41 @@
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  - id: trailing-whitespace
+  - id: end-of-file-fixer
+    exclude: ^.*docs/.*\.md|.*foo.txt$
+  - id: check-yaml
+    args: [ '--multi' ]
+    exclude: ^charts/.*/templates/.*\.yaml|\.gitlab-ci\.yml$
+  - id: check-added-large-files
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.4.1
+  hooks:
+  - id: codespell
+    files: ^.*\.md$
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.12.7
+  hooks:
+  - id: ruff-check
+- repo: https://github.com/DavidAnson/markdownlint-cli2
+  rev: v0.18.1
+  hooks:
+  - id: markdownlint-cli2
+    files: ^.*\.md$
+    exclude: ^.*docs/.*\.md$
+- repo: https://github.com/hadolint/hadolint
+  rev: v2.12.0
+  hooks:
+  - id: hadolint-docker
+- repo: https://github.com/gruntwork-io/pre-commit
+  rev: v0.1.30
+  hooks:
+  - id: helmlint
+    types: [ yaml ]
+    files: ^(charts/app/templates/.*\.yaml)$
+- repo: https://github.com/commitizen-tools/commitizen
+  rev: v4.9.1
+  hooks:
+  - id: commitizen
+    stages: [ commit-msg ]

surf_agentic_base-0.3.0/CITATION.cff

@@ -0,0 +1,25 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata from this file."
+type: software
+title: "surf-agentic-base"
+abstract: >-
+  A base layer for agentic work on research infrastructure. It records what actually ran with the
+  provenance needed to replay and audit it, adjudicates whether a comparison between two agent
+  configurations is sound enough to publish, and carries the primitives every consumer would
+  otherwise write separately and differently.
+authors:
+  - family-names: Podareanu
+    given-names: Damian
+    affiliation: SURF
+version: 0.3.0
+date-released: "2026-09-12"
+license: EUPL-1.2
+repository-code: "https://github.com/saradamian/agentic-base"
+keywords:
+  - agents
+  - provenance
+  - reproducibility
+  - evaluation
+  - model-context-protocol
+  - opentelemetry
+  - hpc

surf_agentic_base-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,15 @@
+# Code of conduct
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/),
+version 2.1. It applies in every space this project runs: the repository, its issues and pull
+requests, and any discussion of it that identifies as such.
+
+In short: be considerate and constructive, accept responsibility and apologise when you get it
+wrong, and take the interests of the community over your own convenience. Harassment,
+discriminatory remarks, publishing others' private information, and sustained disruption are
+not tolerated.
+
+Report violations privately through the repository's security advisory channel at
+<https://github.com/saradamian/agentic-base/security/advisories/new>, which reaches the
+maintainers only. Reports are handled in confidence. The maintainers follow the Covenant's
+enforcement ladder: correction, warning, temporary ban, permanent ban.

surf_agentic_base-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+House rules, kept short so the next reader has less to hold in their head. Most exist because
+something specific went wrong once; `docs/ENGINEERING.md` says what each one cost and which test
+fails when it stops being true.
+
+## Where the reasoning lives
+
+Code is terse. A docstring states purpose and constraints, what a reader needs to use or change
+the thing safely. It does not carry history, justification, or an argument that the change is
+correct; that goes in the commit message and, when it is a decision, in `docs/decisions.md` or
+`docs/architecture/`. A reader who wants to know *why* looks there.
+
+## Two halves, one repository
+
+The **library half** is what other projects import. It installs on Python 3.10 with pydantic,
+pydantic-settings, httpx and PyYAML, and nothing else. Which modules are portable is a list in
+`tests/test_portable_surface.py`, not a paragraph, and its guards fail when the list stops being
+true. The **service half** is an optional extra. If your change makes a portable module import a
+service dependency, the suite tells you.
+
+## Values that belong somewhere else
+
+Anything that is a fact about *where* this runs rather than *what* it does, a registry, a
+hostname, a pull secret, an environment name, does not go in code, chart defaults or the
+Dockerfile. It goes in a deployment overlay outside this repository, and the overlay may only
+add files, never modify ours; `overlay.cfg` declares which paths it owns and a guard refuses a
+change here that creates one. The Dockerfile takes registries as build arguments for this reason.
+The pattern and its tool are in `docs/architecture/deployment-overlay.md`.
+
+## Running the gate
+
+```
+uv sync --group dev --extra service --extra provenance
+.venv/bin/ruff check src tests
+.venv/bin/ruff format --check src tests
+.venv/bin/mypy src tests
+.venv/bin/pytest tests -q
+```
+
+Run pytest **without** `-W ignore`. The repository treats warnings as errors on purpose, and a
+run that suppresses them is a run that cannot fail on the class of defect the policy exists for.
+Two real defects reached the public gate that way in one day. If a warning must be tolerated,
+scope a `filterwarnings` entry to that one message, name the upstream cause, and say when it can
+be removed.
+
+Continuous integration runs the same five steps on 3.10 and 3.14. If your machine has only one,
+the runner is the other.
+
+## Tests
+
+One test per behaviour, at the highest seam that can actually fail. Name the behaviour and the
+condition: `test_a_verdict_from_a_degraded_instrument_is_not_citable`, not `test_citable`. A test
+that no plausible bug would fail should be deleted. A new module needs a test module of the same
+name in the same change; a guard checks.
+
+**Break every guard you add.** Before trusting a check, make the thing it checks wrong and watch
+it go red. A guard that cannot fail is worse than none, because it gets cited.
+
+## Commits and pull requests
+
+Conventional commits: `type(scope): description`, with `feat`, `fix`, `test`, `refactor`,
+`docs`, `chore`, `ci`, `perf`. The pre-commit hook enforces it; install it with
+`pre-commit install --hook-type commit-msg`.
+
+One behaviour per pull request. The description says what changes, what does not, and what is
+deliberately left for later. It must not claim more than the diff delivers.
+
+`main` accepts pull requests only, with the gate green on both interpreters, every review thread
+resolved, and a linear history. There is no required reviewer count while the repository has one
+maintainer; the gate is the reviewer. That changes the day there is a second.
+
+## Versioning and releases
+
+Semantic versioning. The version is the git tag; nothing is edited to cut a release.
+
+- `0.y.z` while the interface is settling. A minor bump may change the public interface, and it
+  is stated in the notes when it does. The import name is `agentic_base`; it was `app` until
+  `0.2.0`. The distribution name is `surf-agentic-base` since `0.3.0`, because `agentic-base` on
+  PyPI belongs to an unrelated project and a pin against it would have installed theirs.
+- Patch releases fix without changing an interface.
+- Tag `vX.Y.Z` on `main`. The release workflow builds the distribution, refuses if the built
+  version differs from the tag, and publishes a GitHub release with generated notes. Nothing goes
+  to a package index from here.
+- `CITATION.cff` carries the version and the release date; update both in the same change that
+  tags.
+
+## Dependencies
+
+Dependabot handles security alerts and the workflow actions. Renovate handles ordinary version
+updates and lock-file maintenance. They are split so they never open the same pull request.
+Actions are pinned by commit hash with the version in a trailing comment; bump both together.