docs: explain project adoption

[jdx]

Summary

• add an opinionated adoption guide based on the mise and aube integrations
• explain hermetic benchmark selection, pinned inputs, main-branch recording, merge-base PR gating, credential separation, and release backfill
• document gate, environment-filtering, and report settings that were missing from the configuration guide
• link the guide from the README, getting-started page, and documentation sidebar

Impact

This gives pre-v1 adopters a complete local-to-CI path while keeping the storage details in the existing git-notes guide. The workflow snippets are deliberately smaller than the production examples and link to mise and aube for hardened implementations.

Validation

• mise run ci
• VitePress production build
• Valgrind counter integration tests

AI-generated by Codex.

---

Note

Low Risk
Documentation-only changes with no runtime or configuration behavior changes.

Overview
Adds an adoption guide (docs/guide/adopting.md) that walks through the full local-to-CI loop: choosing hermetic benchmarks, declaring tak.toml, recording main-branch tips into git notes, gating PRs on merge-base comparisons (with credential stripping before untrusted code runs), optional release backfill, and a rollout checklist. It links to mise and aube as reference implementations.

The configuration guide gains previously undocumented [gate], [env] deny/allow, and [report].credit sections, including CLI/env overrides and precedence.

Navigation is wired from the README, VitePress sidebar, and getting-started “next steps” to the new guide.

^{Reviewed by Cursor Bugbot for commit 07955e7. Bugbot is set up for automated code reviews on this repo. Configure here.}

Summary by CodeRabbit

• Documentation
  • Added a comprehensive guide for adopting tak in a project, including setup, benchmarking, CI integration, release history, and rollout guidance.
  • Documented instruction-count regression gates, environment filtering, report credits, configuration examples, and override behavior.
  • Added navigation links to the new adoption guide from the README and getting-started documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR adds an adoption guide, configuration guidance, CI workflow examples, rollout validation criteria, and links to the new documentation from the README and guide navigation.

Changes

tak Documentation

Layer / File(s)	Summary
Adoption workflow foundations docs/guide/adopting.md	The guide defines benchmark selection, deterministic execution, runner configuration, local integration, and environment checks.
Branch measurement and pull-request gating docs/guide/adopting.md	The guide documents main-branch measurement and note publication, plus pull-request comparisons against merge bases without publishing branch results.
Release backfill and rollout validation docs/guide/adopting.md	The guide adds release backfill instructions, artifact isolation guidance, and rollout validation criteria.
Configuration reference and guide navigation docs/guide/configuration.md, docs/.vitepress/config.mts, docs/guide/getting-started.md, README.md	The documentation describes comparison gates, environment filtering, report credits, and links to the adoption guide.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• jdx/tak#27: Adds and expands tak documentation.
• jdx/tak#28: Introduces the documentation site and related guide structure.

Poem

A rabbit hops through docs so bright,
With benchmark steps aligned just right.
Notes record and gates compare,
Config guides explain with care.
New links point the way—
“Adopt tak!” we cheer today.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the pull request's main change: adding documentation for project adoption.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR adds an adoption guide covering benchmark selection, main-branch recording, pull-request gating, credential separation, and release backfills.

• Documents previously omitted gate, environment-filtering, and report-credit settings.
• Adds the adoption guide to the README, getting-started page, and VitePress sidebar.
• Updates the PR-gating example so an empty comparison explicitly fails the workflow.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/guide/adopting.md	Adds the project-adoption workflow and correctly guards the documented PR gate against empty comparisons.
docs/guide/configuration.md	Documents regression gates, environment filtering, report credits, and configuration precedence.
docs/.vitepress/config.mts	Adds the adoption guide to the documentation sidebar.
docs/guide/getting-started.md	Links readers to the new adoption guide.
README.md	Adds the adoption guide to the documentation index.

_{Reviews (3): Last reviewed commit: "docs: clarify integration examples" | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/guide/adopting.md`:
- Around line 225-231: Update the backfill guidance around the `tak backfill`
example to explicitly require a full repository clone or locally fetched release
tags before running it. Add a verification step that confirms at least one
release was recorded before executing `tak push`, and preserve the existing
backfill command and workflow.
- Around line 238-241: Update the guidance for the backfill workflow to require
executing downloaded release binaries in an ephemeral isolated runner or
container without credentials and with restricted network egress, then pass only
the generated notes artifact to the publishing job. If this isolation cannot be
guaranteed, explicitly limit the guidance to trusted release assets.
- Around line 93-95: Update the guide’s workflow description and the
corresponding sections around the push trigger to match actual behavior: since
the workflow records only the event tip for each push, narrow the claim from
every main-branch commit to each push tip. Apply the same wording adjustment to
the referenced sections, unless the workflow is changed to process every SHA in
the push range.
- Around line 163-178: Update the workflow’s compare preparation around the
compare job and checkout step so private-repository access remains available for
the merge-base and notes fetches without exposing credentials to PR-controlled
measurement code. Move those fetch and comparison operations into a trusted
preparation job, or scope a short-lived read-only credential exclusively to the
post-measurement fetch and tak compare steps while keeping credentials
unavailable during PR code execution.
- Around line 110-114: Update the GitHub Actions examples in adopting.md to
replace every mutable actions/checkout@v7 and jdx/mise-action@v4 reference with
its full immutable commit SHA, including both occurrences in each workflow
section. Preserve the corresponding release version as an inline comment for
maintainers and dependency tooling.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: eb6fcda8-9abe-4f8d-867d-6d0aea82fc68

📥 Commits

Reviewing files that changed from the base of the PR and between cadf576 and b0fc182.

📒 Files selected for processing (5)

• README.md
• docs/.vitepress/config.mts
• docs/guide/adopting.md
• docs/guide/configuration.md
• docs/guide/getting-started.md

Dismissed because a newer commit was pushed; Greptile will re-review the current head.