Enhanced 'vortex-tooling' package docs and relocated its maintenance guide.

[AlexSkrypnyk]

Summary

The drevops/vortex-tooling package's CLAUDE.md was deleted because it shipped to consumer projects and leaked internal maintenance details that have no place on a consumer site. Its content was folded into .vortex/CLAUDE.md (never published to consumers) as a dedicated "Tooling package" section. The package README.md was restructured, expanded, and rewritten to address the reader directly: installation comes first, a new "Extending provisioning" section documents the post-provision hook system as the recommended extension point, the "Customisation" section is reframed as a last resort for patching shipped scripts, and a Testing section explains the unit and integration coverage. .vortex/README.md gained a one-line entry recording where the package is deployed.

Changes

.vortex/tooling/CLAUDE.md - deleted

• Removed entirely; this file was included in the published drevops/vortex-tooling package and exposed internal maintenance notes to every consumer project that installed the dependency.

.vortex/CLAUDE.md - extended

• Updated the subsystems reference to note that tooling/ has no CLAUDE.md of its own, and explains why.
• Added a new "Tooling package" section: package overview, Tests sub-section (BATS unit, PHPUnit integration, manual playground), Script patterns code block, and Publishing notes.
• Added ahoy test-bats to the Quick Commands block and as a step in the script-update workflow (renumbering the subsequent steps).

.vortex/tooling/README.md - restructured, expanded, and reworded

• Rewrote the introduction to drop the enumerated script list and the "shell" wording, and addressed the reader directly throughout ("operations your project relies on", "you run the shipped scripts...").
• Moved Installation to immediately follow the description and removed the redundant Layout section; the intro now notes the package must be added to your Drupal consumer project.
• Added an "Extending provisioning" section documenting the post-provision hook system: executable scripts/provision-*.sh files are discovered and run in filename order by the shipped provision script, illustrated with a project-layout file tree (scripts/, vendor/.../provision, web/, and ...), links to the shipped examples, and a link to the provisioning documentation.
• Reframed "Customisation" as the last resort - patching a shipped script via cweagans/composer-patches only when no post-provision hook can achieve the goal - and explained why in-place edits are lost on update.
• Added a Testing section covering the BATS unit tests and the Vortex functional tests, linking both via absolute URLs (the README is published to a separate repository).

.vortex/README.md - one-line addition

• Added a tooling entry pointing to https://github.com/drevops/vortex-tooling, consistent with the other subsystem entries.

Before / After

README.md section order
──────────────────────────────────────────────────────────────
Before                       After
─────────────                ─────────────
# Vortex Tooling             # Vortex Tooling
(description, enumerated)     (description, no enumeration, "you" voice)
Read-only mirror             Installation
Installation                 Read-only mirror
Layout                       Extending provisioning   <- new (hooks + tree)
Customisation (brief)        Customisation (last resort)
                             Testing
License                      License
──────────────────────────────────────────────────────────────
tooling/CLAUDE.md (shipped)  (removed; consumers no longer receive it)
  leaked to consumers        maintenance guide -> .vortex/CLAUDE.md

Summary by CodeRabbit

• Documentation
  • Consolidated and clarified tooling guidance and maintenance docs, describing shipped scripts and the tooling package behavior.
  • Added install/usage instructions for the distributed tooling package and how to run its helper scripts.
  • Recommended approach for customizing shipped scripts (avoid editing packaged files).
  • Expanded testing docs into unit vs integration tiers and added the ahoy test-bats command.
  • Revised the template-update workflow and quick-command descriptions.

[coderabbitai]

Walkthrough

This PR consolidates tooling guidance into .vortex/CLAUDE.md, updates quick-commands and the template-update checklist, adds a tooling entry to .vortex/README.md, and rewrites .vortex/tooling/README.md for consumer installation, provisioning extension, customization, and testing guidance.

Changes

Tooling Documentation Reorganization

Layer / File(s)	Summary
Main maintenance guide: tooling package guidance .vortex/CLAUDE.md	Expands tooling package section with published behavior, included/excluded package contents, tooling test types, and script conventions. Clarifies src/ as “shipped scripts”, updates Quick Commands (adds ahoy test-bats, adjusts ahoy lint-scripts), and revises the "When updating template scripts" checklist to run ahoy test-bats before snapshot regeneration.
Directory structure documentation .vortex/README.md	Adds a README bullet documenting the tooling subdirectory and noting deployment as the drevops/vortex-tooling package.
Consumer-facing tooling documentation .vortex/tooling/README.md	Rewritten installation and usage: composer require drevops/vortex-tooling, run scripts from vendor/drevops/vortex-tooling/src/<script-name>. Replaces layout with "Extending provisioning" (numeric provision hook sequencing), documents customization via cweagans/composer-patches, and clarifies testing as mocked BATS unit tests vs parent-project integration tests.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through notes and tidy tracks,

Moved the tooling map to central stacks,
Composer paths lined up in rows,
Tests now run before the snapshot shows,
A jaunty burrow of docs now grows.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: enhancing vortex-tooling package documentation and relocating its maintenance guide from .vortex/tooling/CLAUDE.md to .vortex/CLAUDE.md.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/tooling-docs

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.11%. Comparing base (d75239f) to head (513d19a).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2541      +/-   ##
==========================================
- Coverage   86.56%   86.11%   -0.46%     
==========================================
  Files          94       87       -7     
  Lines        4660     4501     -159     
  Branches       47        3      -44     
==========================================
- Hits         4034     3876     -158     
+ Misses        626      625       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Code coverage (threshold: 90%)

  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   98.53% (201/204)

Per-class coverage

Drupal\ys_demo\Plugin\Block\CounterBlock
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 10/ 10)

[AlexSkrypnyk]

Code coverage (threshold: 90%)

  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   98.53% (201/204)

Per-class coverage

Drupal\ys_demo\Plugin\Block\CounterBlock
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 10/ 10)