chore: set up AI assistance by providing AGENTS.md and update-dependencies skill

Author: internaut

.agents/research.md

@@ -11,6 +11,8 @@ Its core purpose is not just to wrap HTTP endpoints, but to hide a number of inc
 
 The project is fairly mature in terms of developer ergonomics: it has strong documentation, broad automated tests, typed Pydantic models, linting/type-checking/security checks, and CI across Python 3.10 to 3.14. The main architectural weakness is concentration of logic in large modules, especially the CLI module. There are also a few places where runtime `assert` statements are used as correctness guards, which is less robust than explicit error handling.
 
+The package version is managed in `pyproject.toml`; the repository is on the `0.2.0.dev9` development line.
+
 ## What The Project Does
 
 At a high level, this repository provides a stable and scriptable interface around Varvis for:
@@ -67,6 +69,8 @@ The package entry point is simple:
 - `src/varvis_connector/__main__.py` creates `VarvisCLI` and runs it
 - `src/varvis_connector/__init__.py` re-exports `VarvisClient` and package version
 
+The package metadata in `pyproject.toml` is set up for public distribution. It includes README, author, GPL-3.0-only license metadata, license file declaration, keywords, PyPI classifiers for Python 3.10 through 3.14, and project URLs for homepage, hosted documentation, repository, issues, and changelog.
+
 ## Runtime Architecture
 
 ### 1. Main abstraction: `VarvisClient`
@@ -614,14 +618,9 @@ The docs are good and materially useful.
 
 The development guide is better than average because it explains not only how to contribute, but why the code contains certain defensive logic.
 
-### Documentation mismatch observed
-
-The development docs mention workflow filenames `docs.yaml` and `release.yaml`, but the repository currently contains:
-
-- `build_and_release.yaml`
-- no `docs.yaml`
+### Documentation publishing
 
-So at least part of the development documentation is stale relative to the current workflow file names.
+The documentation is published through the `docs.yaml` workflow and hosted on GitHub Pages. Production releases trigger the release orchestration workflow, which builds the package and then calls the docs workflow to publish the generated Sphinx documentation.
 
 ## CI / Release / Maintenance Workflow
 
@@ -633,6 +632,7 @@ The project uses:
 
 - `uv` for environment and dependency management
 - `uv_build` as build backend
+- Pydantic, requests, and tqdm as runtime dependencies
 - Ruff for linting/formatting
 - basedpyright for type checking
 - Bandit for security linting
@@ -650,22 +650,34 @@ The repository contains workflows for:
 - scheduled dependency update issue/branch creation
 - gitleaks secret scanning
 - build/release orchestration
+- documentation publishing to GitHub Pages
 
 ### Interesting maintenance choices
 
 - tests and code quality run across Python 3.10 to 3.14
 - tests intentionally serialize CI concurrency to reduce load on the Varvis server
 - dependency updates are partially automated through a scheduled workflow that opens an issue, creates a branch, updates `uv.lock`, and pushes a commit
 - `git-cliff` is used both for changelog generation and for conventional-commit enforcement
+- `uv` uses a seven-day dependency cooldown through `exclude-newer`, with a package-specific exception for `pip`
+- gitleaks ignores version-tag push events as a standalone workflow trigger because the release orchestration workflow calls it explicitly for releases
+- pre-commit mirrors the main local quality gates, including Ruff, Bandit, basedpyright, shellcheck, markdown formatting, and project-local commit/changelog checks
 
 ### Release state
 
-The release workflow is not fully implemented yet:
+The release workflow is fully responsible for package publication on version tags.
+
+`build_and_release.yaml` runs on tags matching `v*.*.*`. It gates releases with gitleaks and dependency audit for all tags. Non-development tags additionally require code quality and tests. Development tags containing `.dev` can build and publish after the security-oriented gates without running the full code quality and test gate inside the release workflow.
+
+The build job creates wheel and source distributions with `make build`, derives the package version from the tag name, and uploads the `dist/` directory as a workflow artifact.
+
+Publication is split by tag type:
 
-- GitHub release publishing step is currently `echo "TODO"`
-- PyPI publishing step is also `echo "TODO"`
+- non-development tags publish artifacts to GitHub Releases
+- non-development tags publish to PyPI through trusted publishing/OIDC
+- development tags publish to TestPyPI
+- all successful release builds trigger the documentation workflow for GitHub Pages
 
-So the repository has strong scaffolding for release automation, but not a fully completed publishing pipeline.
+GitHub release notes are generated from the current top section of `CHANGELOG.md`, and the release assets include both wheel and source distribution files.
 
 ## Code Quality Assessment
 
@@ -718,9 +730,9 @@ This is not fatal, but it is a tradeoff toward operator convenience over interna
 
 Many command handlers call `exit(1)` directly. Others rely on the top-level `VarvisCLI.run()` exception trap. The result is a somewhat mixed control-flow style.
 
-#### Minor stale docs / naming drift
+#### Release workflow complexity
 
-There are a few documentation/workflow naming mismatches, which suggests the documentation is maintained actively but not perfectly synchronized with recent automation changes.
+The release workflow is one of the higher-risk pieces of repository automation. It coordinates security gates, optional quality/test gates for development tags, package artifact upload/download, GitHub Release publication, PyPI/TestPyPI publication, changelog extraction, and documentation publishing. Small YAML changes here can affect published artifacts directly.
 
 ## Specific Findings And Nuances Worth Remembering
 
@@ -731,7 +743,7 @@ There are a few documentation/workflow naming mismatches, which suggests the doc
 - The CLI is intentionally pipeline-friendly and carefully avoids polluting stdout when data output is expected there.
 - Virtual panel update performs client-side merge behavior by fetching the current remote panel first.
 - File download handling has decent filename/path safety checks.
-- The project currently looks like an initial public release with mature tooling but a short external changelog history.
+- The project is an early but actively publishable package line, with mature tooling and an implemented release pipeline rather than only local build support.
 
 ## Suggested Reading Order For Future Work
 

.agents/skills/update-dependencies/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: update-dependencies
+description: Update all dependencies in the current project, including Python packages in `uv.lock` and pre-commit hook revisions in `.pre-commit-config.yaml`. Use when the user asks to "update dependencies", "update all dependencies", refresh the lockfile, refresh pre-commit hooks, or bring direct dependency minimum versions in `pyproject.toml` up to the versions actually adopted after an update.
+---
+
+# Update Dependencies
+
+## Overview
+
+Update this repository's dependencies with the project's own automation, validate the result end to end, fix small breakages, and roll back only the dependency updates that are not worth fixing. Keep the final state intentional and report exactly what changed.
+
+## Workflow
+
+1. Read `AGENTS.md`, `.agents/research.md`, `pyproject.toml`, `Makefile`, and `.pre-commit-config.yaml` before making changes.
+2. Capture the starting state for later reporting:
+   - direct dependencies from `pyproject.toml`
+   - optional dependencies and dependency groups from `pyproject.toml`
+   - pre-commit hook revisions from `.pre-commit-config.yaml`
+   - current version pins in `uv.lock` for direct dependencies if needed
+3. Run the project's update command:
+
+```bash
+make depupgrade
+```
+
+1. Inspect which files changed. Expect at least:
+   - `uv.lock`
+   - `.pre-commit-config.yaml`
+   - sometimes `pyproject.toml`
+2. Update minimum versions in `pyproject.toml` for direct dependencies that were actually upgraded.
+   - Only change direct dependencies already listed in `pyproject.toml`.
+   - Do not add or remove dependencies unless the update flow clearly requires it.
+   - Keep version specifiers simple and consistent with the file's current style, usually `>=<new_version>`.
+3. Run the full validation flow after the update.
+4. If validation fails, fix small compatibility issues directly.
+5. If a failure is caused by one updated dependency and the fix is too large for the update task, roll back only that dependency update, then rerun validation.
+6. Summarize all dependency changes and any rollback decisions.
+7. Update `.agents/research.md` if the repository-specific dependency update workflow or skill inventory changed in a way future work should know about.
+
+## Validation
+
+Load environment variables from `.env` before validation commands that need them.
+
+Run the full repo checks expected for non-trivial code changes:
+
+```bash
+test -f .env && set -a && source .env && set +a
+ruff check
+ruff format
+basedpyright
+bandit -c pyproject.toml -r src/
+make testall
+make build
+make docs
+```
+
+Also refresh pre-commit hook state when useful:
+
+```bash
+uv run pre-commit run --all-files
+```
+
+If a command fails because the update changed generated files or formatting, fix that and rerun the failed command plus any downstream checks.
+
+## Failure Triage
+
+Use this order:
+
+1. Determine whether the failure is caused by the dependency update or by unrelated local dirt.
+2. If unrelated local dirt exists, avoid reverting it and work only with the update-related files.
+3. If the failure is clearly caused by a small API or typing change, patch the project and keep the newer dependency.
+4. If the failure points to one upgraded dependency and the fix would be broad, risky, or time-consuming, roll back that dependency instead of forcing a large refactor.
+
+Treat these as "too big" unless the user asked for broader maintenance:
+
+- wide API migrations across multiple modules
+- behavior changes that require redesign rather than adaptation
+- new dependency-family incompatibilities that spread across the repo
+
+## Rolling Back One Dependency
+
+Prefer the narrowest rollback possible.
+
+For a direct dependency:
+
+1. Find the previous working version from the git diff or pre-update state.
+2. Restore the intended minimum version in `pyproject.toml`.
+3. Re-lock to the previous version for that package.
+
+For a transitive dependency:
+
+1. Re-lock that package to the previous version without broad manual edits.
+2. Keep the rest of the update set intact.
+
+Useful commands:
+
+```bash
+uv lock -P <package>==<old_version>
+uv sync --all-groups --all-extras
+```
+
+If pre-commit hook updates cause the problem and the issue is not worth fixing, revert only the affected hook revision in `.pre-commit-config.yaml` and rerun validation.
+
+## Reporting
+
+Always report:
+
+- direct dependencies updated in `pyproject.toml`
+- point out major-version changes in direct dependencies
+- package updates reflected in `uv.lock`
+- pre-commit hook revision changes
+- any fixes made to keep the update
+- any dependency rolled back and why
+- validation commands run and their final outcome
+
+Prefer a concise grouped summary rather than dumping raw lockfile diffs, but include exact package names and final versions.

.agents/skills/update-dependencies/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Update Dependencies"
+  short_description: "Update project dependencies safely"
+  default_prompt: "Use $update-dependencies to update project dependencies, validate the result, and report the changes."

AGENTS.md

@@ -0,0 +1,40 @@
+# AGENTS.md
+
+## Project context
+
+Read `.agents/research.md` **in depth** to get an overview about this project.
+
+## Testing
+
+- load the environment variables in `.env` before running tests
+- test only what you need during implementation (i.e. only affected / new tests)
+- make a full test run when completing a task
+
+## Rules
+
+General rules:
+
+- do not install or update any dependencies on your own; if you think installing or updating dependencies is necessary
+  give a notice so the user can do this manually
+- prefer simple and short solutions over complex ones
+- only move code to separate helper functions / methods if it is needed (i.e. called in more than one place)
+- write a short comment before each code block that summarizes what the block does
+- comments don't have to be full sentences but rather short notes, starting with lower case, ending without a period
+- never update the changelog -- this is done automatically
+
+To complete an implementation tasks other than minor tasks like documentation work, make sure:
+
+- new functions / methods / classes have proper docstrings
+- updated functions / methods / classes have updated docstrings
+- write full sentences in docstrings
+- all tests pass
+- if a bash script was modified, `shellcheck -x` must pass
+- `ruff check` must pass (if not, try `ruff check --fix` to fix any problems)
+- run `ruff format` to format the generated / updated code
+- `basedpyright` must pass
+- `bandit -c pyproject.toml -r src/` must pass
+- the package can be built successfully via `make build`
+- the documentation can be built successfully via `make docs`
+- `.agents/research.md` is updated according to the changes introduced to complete the task; treat
+  `.agents/research.md` as knowledge base that should always reflect the current state of the project;
+  don't use language that indicates changes -- the document is *not* a changelog