taskill 0.1.2__tar.gz → 0.1.3__tar.gz

{taskill-0.1.2 → taskill-0.1.3}/.gitignore

@@ -2,6 +2,8 @@
 examples/.env.example
 vscode-extension/.env.example
 .idea
+.pyqual
+.taskill
 litellm_config.yaml
 litellm-config.yaml
 .code2llm_cache

taskill-0.1.3/.windsurf/workflows/daily-docs-update.md

@@ -0,0 +1,158 @@
+---
+description: Daily documentation update workflow across multiple projects
+---
+
+# Daily Documentation Update Workflow
+
+This workflow automates the routine task of keeping README.md, CHANGELOG.md, and TODO.md in sync across multiple projects.
+
+## Prerequisites
+
+1. Install taskill: `pip install taskill[mcp,schedule]`
+2. Set up OPENROUTER_API_KEY in .env files (or use Windsurf MCP)
+3. Ensure each project has a taskill.yaml config
+
+## Single Project
+
+```bash
+cd /path/to/project
+taskill status          # Preview what would change
+taskill run             # Execute the update
+taskill run --dry-run   # Preview without writing
+```
+
+## Multiple Projects (Bulk Run)
+
+### Option 1: Using CLI command
+
+```bash
+# Run taskill on all repos under ~/github
+taskill bulk-run --root ~/github --max-depth 2
+
+# Dry-run to preview
+taskill bulk-run --root ~/github --max-depth 2 --dry-run
+
+# Force run (ignore triggers)
+taskill bulk-run --root ~/github --max-depth 2 --force
+
+# Filter specific repos (repeatable)
+taskill bulk-run --root ~/github --filter taskill --filter testql
+
+# Limit number of projects per run (useful for rate-limited LLMs)
+taskill bulk-run --root ~/github --max-projects 5
+
+# Use a shared config + JSON output
+taskill bulk-run --root ~/github \
+  --shared-config ~/github/taskill.yaml \
+  --max-projects 10 \
+  --json
+```
+
+### Option 2: Using the shell wrapper
+
+`daily_update.sh` wraps the CLI and reads its defaults from `.env`:
+
+```bash
+# .env in the project root
+GITHUB_ROOT=$HOME/github
+TASKILL_MAX_DEPTH=2
+TASKILL_MAX_PROJECTS=10
+TASKILL_DRY_RUN=false
+TASKILL_FORCE=false
+TASKILL_FILTER=oqlos,semcod    # comma-separated
+```
+
+```bash
+./daily_update.sh                       # uses .env defaults
+./daily_update.sh --dry-run             # preview only
+./daily_update.sh --force               # ignore triggers
+./daily_update.sh --filter taskill,testql
+./daily_update.sh --root /tmp/projects  # override target directory
+```
+
+### Option 3: Using Python script
+
+```python
+from pathlib import Path
+from taskill.bulk import bulk_run
+
+result = bulk_run(
+    root=Path("/home/tom/github"),
+    shared_config=Path("/home/tom/github/taskill.yaml"),  # optional
+    max_depth=2,
+    max_projects=10,    # 0 = unlimited
+    force=False,
+    dry_run=False,
+    repo_filter=["taskill", "testql"],  # optional substring match
+)
+
+print(result.summary())
+# 3/5 ran, 2 changed, 1 skipped, 0 errors
+
+for repo, repo_result in result.per_repo.items():
+    print(repo.name, "ran" if repo_result.ran else "skipped",
+          repo_result.files_changed)
+```
+
+## What taskill does
+
+1. **CHANGELOG.md**: Appends new entries under [Unreleased] based on git commits
+2. **TODO.md**: Moves completed items to "Done (moved to CHANGELOG)" section
+3. **README.md**: Updates status block between markers (HEAD, coverage, failing tests)
+4. **SUMD.md/SUMR.md**: Reads these files as context for the LLM provider
+
+## Triggers
+
+By default, taskill only runs when:
+- At least 24 hours since last run
+- At least 1 new commit
+- Files changed threshold met
+- SUMD.md or SUMR.md modified
+
+Use `--force` to override triggers.
+
+## Automation
+
+### Cron job (daily at 6 AM)
+
+```cron
+0 6 * * * cd /home/tom/github && /usr/local/bin/taskill bulk-run --root . --max-depth 2 >> ~/.taskill.log 2>&1
+```
+
+### Systemd timer
+
+See `examples/systemd-timer/taskill.service` and `taskill.timer`.
+
+## Shared Config
+
+Pass a shared `taskill.yaml` via `--shared-config` to provide a default config
+for all discovered repos:
+
+```bash
+# ~/github/taskill.yaml (the shared base)
+triggers:
+  min_hours_since_last_run: 24
+  min_commits_since_last_run: 1
+providers:
+  - name: openrouter
+    enabled: true
+  - name: algorithmic
+    enabled: true
+```
+
+Resolution order per repo:
+
+1. `<repo>/taskill.yaml` (highest priority)
+2. `<repo>/.taskill.yaml`
+3. `--shared-config` rebased onto the repo's path
+4. Built-in defaults
+
+Each repo can override only what it needs by dropping a partial `taskill.yaml`
+into its own root.
+
+## Troubleshooting
+
+- Use `--verbose` flag for debug output
+- Check `.taskill/state.json` for last run state
+- Use `--dry-run` to preview changes
+- Check provider chain in taskill.yaml (windsurf_mcp → openrouter → algorithmic)

{taskill-0.1.2 → taskill-0.1.3}/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [0.1.10] - 2026-04-25
 
+### Fixed
+- Fix string-concat issues (ticket-b239ce82)
+- Fix unused-imports issues (ticket-37e0cb27)
+- Fix llm-generated-code issues (ticket-1c7d5f6a)
+- Fix smart-return-type issues (ticket-a7a0a53e)
+- Fix unused-imports issues (ticket-8dae20d0)
+
+## [0.1.10] - 2026-04-25
+
 ### Fixed
 - Fix unused-imports issues (ticket-db5e9dd3)
 - Fix magic-numbers issues (ticket-dba8c3c5)
@@ -52,6 +61,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `taskill bulk-run` command for fleet-wide hygiene runs across multiple git repos (ROADMAP v0.5)
+- `taskill.bulk` module with `find_repos`, `resolve_repo_config`, `bulk_run`, and `BulkResult` (exported from `taskill`)
+- `--max-projects` CLI flag and `max_projects` parameter on `bulk_run` to cap per-run project count
+- `--shared-config` flag so a parent directory's `taskill.yaml` can act as the base for all child repos
+- `--filter` flag (repeatable) to limit `bulk-run` to repos whose name matches a substring
+- Per-repo config resolution: `<repo>/taskill.yaml` → `<repo>/.taskill.yaml` → shared → defaults
+- Plugin protocol for providers via `[project.entry-points."taskill.providers"]` and `discover_providers()` (ROADMAP v0.2.1)
+- Plugin protocol for document updaters via `[project.entry-points."taskill.updaters"]` and `discover_updaters()` (ROADMAP v0.2.3)
+- `DocumentUpdater` ABC and `UpdateResult` dataclass in `taskill.updaters.base`
+- `daily_update.sh` shell wrapper around `bulk-run` with `.env`-driven defaults
+
+### Changed
+- Built-in providers (`windsurf_mcp`, `openrouter`, `algorithmic`) re-registered via entry points instead of a hard-coded registry
+- Built-in updaters refactored into classes (`ChangelogUpdater`, `TodoUpdater`, `ReadmeUpdater`); legacy `update_changelog` / `update_todo` / `update_readme` functions kept as backward-compatible wrappers
+
+### Docs
+- README: new "Bulk / fleet-wide runs" and "Extending taskill" sections
+- ROADMAP: marked v0.2.1, v0.2.3, and v0.5 baseline as shipped
+
+## [0.1.3] - 2026-04-25
+
+### Docs
+- Update .windsurf/workflows/daily-docs-update.md
+- Update CHANGELOG.md
+- Update README.md
+- Update ROADMAP.md
+- Update SUMD.md
+- Update SUMR.md
+- Update TODO.md
+- Update project/README.md
+- Update project/context.md
+
+### Test
+- Update tests/test_bulk.py
+
+### Other
+- Update .env.example
+- Update .gitignore
+- Update app.doql.less
+- Update daily_update.sh
+- Update planfile.yaml
+- Update project.sh
+- Update project/analysis.toon.yaml
+- Update project/calls.mmd
+- Update project/calls.png
+- Update project/calls.toon.yaml
+- ... and 13 more files
+
 ## [0.1.2] - 2026-04-25
 
 ### Docs

{taskill-0.1.2 → taskill-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskill
-Version: 0.1.2
+Version: 0.1.3
 Summary: Daily project hygiene: keep README / CHANGELOG / TODO in sync with reality. LLM-first, algorithmic fallback.
 Project-URL: Homepage, https://github.com/oqlos/taskill
 Project-URL: Issues, https://github.com/oqlos/taskill/issues
@@ -37,10 +37,10 @@ Description-Content-Type: text/markdown
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.2-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.15-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-2.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.3-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.30-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-2.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $0.1500 (1 commits)
+- 🤖 **LLM usage:** $0.3000 (2 commits)
 - 👤 **Human dev:** ~$200 (2.0h @ $100/h, 30min dedup)
 
 Generated on 2026-04-25 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
@@ -81,7 +81,22 @@ Every run produces three (idempotent) edits:
 
 1. **`CHANGELOG.md`** — appends new entries under `## [Unreleased]`, grouped by Conventional Commit type (`### Added`, `### Fixed`, `### Performance`, etc.). Uses [Keep a Changelog](https://keepachangelog.com/) layout. Existing entries are deduplicated.
 2. **`TODO.md`** — moves completed items to a `## Done (moved to CHANGELOG)` section, and appends `TODO:` / `FIXME:` markers found in new commit bodies under `## Discovered`.
-3. **`README.md`** — refreshes only the block between `<!-- taskill:status:start -->` and `<!-- taskill:status:end -->` markers (HEAD, coverage, failing tests, summary). Never touches the rest of the file.
+3. **`README.md`** — refreshes only the block between `<!-- taskill:status:start -->
+
+## Status
+
+_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 09:23 UTC_
+
+| Metric | Value |
+|---|---|
+| HEAD | `4618c29` |
+| Coverage | — |
+| Failing tests | — |
+| Commits in last cycle | 0 |
+
+> No changes were made to the project since the last taskill run.
+
+<!-- taskill:status:end -->` markers (HEAD, coverage, failing tests, summary). Never touches the rest of the file.
 
 ## Provider chain
 
@@ -128,6 +143,18 @@ triggers:
 0 6 * * * cd /path/to/project && /usr/local/bin/taskill run >> ~/.taskill.log 2>&1
 ```
 
+### Bulk run (multiple projects)
+
+For fleet-wide hygiene across many repos:
+
+```bash
+taskill bulk-run --root ~/github --max-depth 2
+taskill bulk-run --root ~/github --max-depth 2 --dry-run  # preview
+taskill bulk-run --root ~/github --filter taskill --filter testql  # filter repos
+```
+
+See `/daily-docs-update` workflow for complete documentation.
+
 ### GitHub Actions
 
 See `examples/github-action.yml`. Triggers on `push` to main, runs `taskill run`, opens a PR if files changed.
@@ -149,10 +176,138 @@ taskill run            # execute (respects triggers)
 taskill run --force    # ignore triggers
 taskill run --dry-run  # don't write files or state
 taskill run --json     # machine-readable output
+taskill bulk-run       # run across all git repos in a directory
 taskill release X.Y.Z  # promote [Unreleased] → versioned heading
 taskill clean-todo     # wipe TODO.md (after a release)
 ```
 
+## Bulk / fleet-wide runs
+
+When you maintain many small repos (a personal "github" folder, a self-hosted
+GitLab group, a monorepo of independent packages), `taskill bulk-run` runs the
+same hygiene job across all of them with a single command:
+
+```bash
+# Scan ~/github (depth 2), use a shared taskill.yaml as the base config
+taskill bulk-run --root ~/github --shared-config ~/github/taskill.yaml
+
+# Same, but only run on repos whose name matches one of the filters
+taskill bulk-run --root ~/github -f oqlos -f semcod
+
+# Process at most 5 projects per run (useful for rate-limited LLMs)
+taskill bulk-run --root ~/github --max-projects 5
+
+# Preview without writing anything
+taskill bulk-run --root ~/github --dry-run --force
+
+# Machine-readable summary for CI / dashboards
+taskill bulk-run --root ~/github --json
+```
+
+### Config resolution per repo
+
+Per-repo `taskill.yaml` (or `.taskill.yaml`) takes precedence over the shared
+config, so you can have one default policy plus per-project overrides. Repos
+without any local config inherit the shared one with their own `project_root`.
+
+Resolution order for each discovered repo:
+
+1. `<repo>/taskill.yaml` — local override (highest priority)
+2. `<repo>/.taskill.yaml` — alternative local override
+3. Shared config from `--shared-config`, rebased onto the repo
+4. Built-in defaults
+
+### Discovery rules
+
+`bulk-run` walks the directory tree starting at `--root` up to `--max-depth`
+levels deep (default 2). A directory containing a `.git` entry is treated as a
+repo, and `bulk-run` does **not** descend into nested repos. Hidden directories
+and common noise (`node_modules`, `__pycache__`, `.venv`, `dist`, `build`,
+`target`, `.tox`, `.pytest_cache`) are skipped automatically.
+
+### Daily-run wrapper
+
+A shell wrapper (`daily_update.sh`) reads its defaults from `.env`:
+
+```bash
+# .env
+GITHUB_ROOT=$HOME/github
+TASKILL_MAX_DEPTH=2
+TASKILL_MAX_PROJECTS=10        # cap per cron tick
+TASKILL_DRY_RUN=false
+TASKILL_FORCE=false
+TASKILL_FILTER=oqlos,semcod    # comma-separated
+```
+
+```bash
+./daily_update.sh                              # uses .env
+./daily_update.sh --dry-run                    # CLI override
+./daily_update.sh --root /tmp/my-projects      # different root
+./daily_update.sh --filter taskill,testql      # narrow scope
+```
+
+## Extending taskill: providers and updaters as plugins
+
+Both providers (LLM/algorithmic backends) and document updaters (CHANGELOG /
+TODO / README writers) are discovered through Python entry points, so a
+third-party package can register a new provider or updater without touching
+this codebase.
+
+### Custom provider
+
+```toml
+# my_pkg/pyproject.toml
+[project.entry-points."taskill.providers"]
+my_provider = "my_pkg.provider:MyProvider"
+```
+
+```python
+# my_pkg/provider.py
+from taskill.providers.base import Provider, GeneratedDocs
+
+class MyProvider(Provider):
+    name = "my_provider"
+
+    def is_available(self) -> bool:
+        return True
+
+    def generate(self, context) -> GeneratedDocs:
+        ...
+```
+
+Then reference it from `taskill.yaml` like any built-in:
+
+```yaml
+providers:
+  - name: my_provider
+    enabled: true
+    options: { ... }
+  - name: algorithmic
+    enabled: true
+```
+
+### Custom updater
+
+```toml
+[project.entry-points."taskill.updaters"]
+wiki = "my_pkg.wiki:WikiUpdater"
+```
+
+```python
+from taskill.updaters.base import DocumentUpdater, UpdateResult
+
+class WikiUpdater(DocumentUpdater):
+    name = "wiki"
+
+    def apply(self, path, snapshot, docs) -> UpdateResult:
+        ...
+        return UpdateResult(changed=True, path=path, updater_name=self.name)
+```
+
+Built-in updaters (`changelog`, `todo`, `readme`) are registered the same way,
+so removing or replacing them is just a matter of the entry-point taking
+precedence.
+
 ## Configuration reference
 
 See [`taskill.yaml`](./taskill.yaml) at the repo root for the annotated default config.
@@ -188,5 +343,18 @@ Licensed under Apache-2.0.
 ## Status
 
 <!-- taskill:status:start -->
-_Bootstrapped — no live project status yet. Will populate after first `taskill run`._
+
+## Status
+
+_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 09:23 UTC_
+
+| Metric | Value |
+|---|---|
+| HEAD | `4618c29` |
+| Coverage | — |
+| Failing tests | — |
+| Commits in last cycle | 0 |
+
+> No changes were made to the project since the last taskill run.
+
 <!-- taskill:status:end -->

{taskill-0.1.2 → taskill-0.1.3}/README.md

@@ -3,10 +3,10 @@
 
 ## AI Cost Tracking
 
-![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.2-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
-![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.15-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-2.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
+![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.1.3-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![AI Cost](https://img.shields.io/badge/AI%20Cost-$0.30-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-2.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)
 
-- 🤖 **LLM usage:** $0.1500 (1 commits)
+- 🤖 **LLM usage:** $0.3000 (2 commits)
 - 👤 **Human dev:** ~$200 (2.0h @ $100/h, 30min dedup)
 
 Generated on 2026-04-25 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)
@@ -47,7 +47,22 @@ Every run produces three (idempotent) edits:
 
 1. **`CHANGELOG.md`** — appends new entries under `## [Unreleased]`, grouped by Conventional Commit type (`### Added`, `### Fixed`, `### Performance`, etc.). Uses [Keep a Changelog](https://keepachangelog.com/) layout. Existing entries are deduplicated.
 2. **`TODO.md`** — moves completed items to a `## Done (moved to CHANGELOG)` section, and appends `TODO:` / `FIXME:` markers found in new commit bodies under `## Discovered`.
-3. **`README.md`** — refreshes only the block between `<!-- taskill:status:start -->` and `<!-- taskill:status:end -->` markers (HEAD, coverage, failing tests, summary). Never touches the rest of the file.
+3. **`README.md`** — refreshes only the block between `<!-- taskill:status:start -->
+
+## Status
+
+_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 09:23 UTC_
+
+| Metric | Value |
+|---|---|
+| HEAD | `4618c29` |
+| Coverage | — |
+| Failing tests | — |
+| Commits in last cycle | 0 |
+
+> No changes were made to the project since the last taskill run.
+
+<!-- taskill:status:end -->` markers (HEAD, coverage, failing tests, summary). Never touches the rest of the file.
 
 ## Provider chain
 
@@ -94,6 +109,18 @@ triggers:
 0 6 * * * cd /path/to/project && /usr/local/bin/taskill run >> ~/.taskill.log 2>&1
 ```
 
+### Bulk run (multiple projects)
+
+For fleet-wide hygiene across many repos:
+
+```bash
+taskill bulk-run --root ~/github --max-depth 2
+taskill bulk-run --root ~/github --max-depth 2 --dry-run  # preview
+taskill bulk-run --root ~/github --filter taskill --filter testql  # filter repos
+```
+
+See `/daily-docs-update` workflow for complete documentation.
+
 ### GitHub Actions
 
 See `examples/github-action.yml`. Triggers on `push` to main, runs `taskill run`, opens a PR if files changed.
@@ -115,10 +142,138 @@ taskill run            # execute (respects triggers)
 taskill run --force    # ignore triggers
 taskill run --dry-run  # don't write files or state
 taskill run --json     # machine-readable output
+taskill bulk-run       # run across all git repos in a directory
 taskill release X.Y.Z  # promote [Unreleased] → versioned heading
 taskill clean-todo     # wipe TODO.md (after a release)
 ```
 
+## Bulk / fleet-wide runs
+
+When you maintain many small repos (a personal "github" folder, a self-hosted
+GitLab group, a monorepo of independent packages), `taskill bulk-run` runs the
+same hygiene job across all of them with a single command:
+
+```bash
+# Scan ~/github (depth 2), use a shared taskill.yaml as the base config
+taskill bulk-run --root ~/github --shared-config ~/github/taskill.yaml
+
+# Same, but only run on repos whose name matches one of the filters
+taskill bulk-run --root ~/github -f oqlos -f semcod
+
+# Process at most 5 projects per run (useful for rate-limited LLMs)
+taskill bulk-run --root ~/github --max-projects 5
+
+# Preview without writing anything
+taskill bulk-run --root ~/github --dry-run --force
+
+# Machine-readable summary for CI / dashboards
+taskill bulk-run --root ~/github --json
+```
+
+### Config resolution per repo
+
+Per-repo `taskill.yaml` (or `.taskill.yaml`) takes precedence over the shared
+config, so you can have one default policy plus per-project overrides. Repos
+without any local config inherit the shared one with their own `project_root`.
+
+Resolution order for each discovered repo:
+
+1. `<repo>/taskill.yaml` — local override (highest priority)
+2. `<repo>/.taskill.yaml` — alternative local override
+3. Shared config from `--shared-config`, rebased onto the repo
+4. Built-in defaults
+
+### Discovery rules
+
+`bulk-run` walks the directory tree starting at `--root` up to `--max-depth`
+levels deep (default 2). A directory containing a `.git` entry is treated as a
+repo, and `bulk-run` does **not** descend into nested repos. Hidden directories
+and common noise (`node_modules`, `__pycache__`, `.venv`, `dist`, `build`,
+`target`, `.tox`, `.pytest_cache`) are skipped automatically.
+
+### Daily-run wrapper
+
+A shell wrapper (`daily_update.sh`) reads its defaults from `.env`:
+
+```bash
+# .env
+GITHUB_ROOT=$HOME/github
+TASKILL_MAX_DEPTH=2
+TASKILL_MAX_PROJECTS=10        # cap per cron tick
+TASKILL_DRY_RUN=false
+TASKILL_FORCE=false
+TASKILL_FILTER=oqlos,semcod    # comma-separated
+```
+
+```bash
+./daily_update.sh                              # uses .env
+./daily_update.sh --dry-run                    # CLI override
+./daily_update.sh --root /tmp/my-projects      # different root
+./daily_update.sh --filter taskill,testql      # narrow scope
+```
+
+## Extending taskill: providers and updaters as plugins
+
+Both providers (LLM/algorithmic backends) and document updaters (CHANGELOG /
+TODO / README writers) are discovered through Python entry points, so a
+third-party package can register a new provider or updater without touching
+this codebase.
+
+### Custom provider
+
+```toml
+# my_pkg/pyproject.toml
+[project.entry-points."taskill.providers"]
+my_provider = "my_pkg.provider:MyProvider"
+```
+
+```python
+# my_pkg/provider.py
+from taskill.providers.base import Provider, GeneratedDocs
+
+class MyProvider(Provider):
+    name = "my_provider"
+
+    def is_available(self) -> bool:
+        return True
+
+    def generate(self, context) -> GeneratedDocs:
+        ...
+```
+
+Then reference it from `taskill.yaml` like any built-in:
+
+```yaml
+providers:
+  - name: my_provider
+    enabled: true
+    options: { ... }
+  - name: algorithmic
+    enabled: true
+```
+
+### Custom updater
+
+```toml
+[project.entry-points."taskill.updaters"]
+wiki = "my_pkg.wiki:WikiUpdater"
+```
+
+```python
+from taskill.updaters.base import DocumentUpdater, UpdateResult
+
+class WikiUpdater(DocumentUpdater):
+    name = "wiki"
+
+    def apply(self, path, snapshot, docs) -> UpdateResult:
+        ...
+        return UpdateResult(changed=True, path=path, updater_name=self.name)
+```
+
+Built-in updaters (`changelog`, `todo`, `readme`) are registered the same way,
+so removing or replacing them is just a matter of the entry-point taking
+precedence.
+
 ## Configuration reference
 
 See [`taskill.yaml`](./taskill.yaml) at the repo root for the annotated default config.
@@ -154,5 +309,18 @@ Licensed under Apache-2.0.
 ## Status
 
 <!-- taskill:status:start -->
-_Bootstrapped — no live project status yet. Will populate after first `taskill run`._
+
+## Status
+
+_Last updated by [taskill](https://github.com/oqlos/taskill) at 2026-04-25 09:23 UTC_
+
+| Metric | Value |
+|---|---|
+| HEAD | `4618c29` |
+| Coverage | — |
+| Failing tests | — |
+| Commits in last cycle | 0 |
+
+> No changes were made to the project since the last taskill run.
+
 <!-- taskill:status:end -->