docs: write the four remaining engine-capability docs - #87
Merged
Conversation
Completes the docs/ backlog. Adds:
- engine/templates.md — .tmpl content substitution: the opt-in, the
{{.ProjectName}} data model, escaping literal braces, and why verbatim
copy is the default.
- engine/path-templating.md — {{.ProjectName}} in file paths, and the
.tmpl workaround that keeps cmd/{{.ProjectName}}/ from breaking
`go build ./...` in the template tree.
- engine/common-overlay.md — the flavor-then-common layering, the shared
claimed-path set that makes the flavor win on collisions, and Overlay()
as the single-layer writer add-tracker uses.
- engine/done-gate.md — what the shipped check.sh runs, and the
step (hard) vs maybe_step (skip-missing-recipe) split that lets one
script serve every flavor.
Each leads with what the capability is, links source with file:line, and
carries a worked example. docs/README.md: all four marked DONE, backlog
cleared; flavor-hooks.md drops the "(TODO)" on its common-overlay link.
Cross-doc anchors verified; vet and tests pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follows #86 (the README/docs polish, now merged). Completes the
docs/backlog — every subcommand, flag, flavor, and engine capability now has a doc entry.New docs
engine/templates.md—.tmplcontent substitution: the opt-in, the{{.ProjectName}}data model, escaping literal braces ({{"{{"}}), and why verbatim copy is the default (Helm/Ansible/Actions files with native{{ }}).engine/path-templating.md—{{.ProjectName}}in file paths, and the.tmplworkaround that keepscmd/{{.ProjectName}}/from breakinggo build ./...in the template tree.engine/common-overlay.md— flavor-then-common layering, the sharedclaimed-path set that makes the flavor win on collisions, andOverlay()as the single-layer writeradd-trackeruses.engine/done-gate.md— what the shippedcheck.shruns, and thestep(hard) vsmaybe_step(skip-missing-recipe) split that lets one script serve every flavor.Each leads with what the capability is, links source with
file:line, and carries a worked example — matching the house style offlavor-hooks.md/releases.md.Index
docs/README.md: all four marked DONE, backlog removed (it's empty now).flavor-hooks.mddrops the(TODO)on itscommon-overlay.mdlink, and the/feature-docskill note no longer references a TODO backlog.Verification
All source line refs were read directly from the code. Cross-doc anchors (
iac#template-files-and-the-jinja-gotcha,flavor-hooks#commontemplates, each flavor's#justfile-recipes) verified to resolve.go vetandgo test ./...pass.🤖 Generated with Claude Code