Foreign template engines would split validation and documentation across ecosystems.
FAQ and troubleshooting
Platform spec article
FAQ and troubleshooting
Spec standingStandard
-
Use beskid.template.v1 only
Context
Decision
The platform must use
beskid.template.v1only. Foreign engine schemas are forbidden in spec, CLI, and pckg.Consequences
Single parser and validator in tooling; template docs stay in-repo.
Verification anchors
CI grep excluding foreign schema identifiers under
compiler/and platform-spec tooling tree. -
Use {{symbolId}} delimiters in template text
Context
Template authors need delimiter syntax distinct from Beskid source.
Decision
Text files must use
{{symbolName}}placeholders; optionalsourceNamerewriting applies to paths and identifiers.Consequences
Editors can highlight unmatched braces; substitution tests stay deterministic.
Verification anchors
Golden substitution tests under planned
beskid_teststemplate fixtures. -
Validation runs on instantiation output only, not template project build.
Context
Requiring
beskid buildon template sources slows authoring and blocks non-host template layouts.Decision
Template packages need not compile at the template project root. Tooling must validate via instantiation output builds.
Consequences
Faster template iteration; CI runs instantiate-then-build on consumer output.
Verification anchors
beskid.templates.*CI pipeline; plannedbeskid_teststemplate fixtures. -
Implicit corelib
Context
Hosts need standard library.
Decision
Inject corelib; forbid noCorelib flags.
Consequences
Simpler manifests.
Verification anchors
E18xx linter.
-
Three template kinds
Context
Workspace, project, item flows.
Decision
Support all three via tags.type.
Consequences
One engine.
Verification anchors
Three beskid_tests fixtures.
-
Path and git sources
Context
Local workflows.
Decision
Resolve registry, path, and git.
Consequences
beskid new flags.
Verification anchors
Git/path integration tests.
-
No constraints
Context
DSL delay.
Decision
No constraint blocks in schema.
Consequences
Simpler v1.
Verification anchors
Reject constraints key.
-
Post-actions
Context
Extensibility.
Decision
Documented action ids, no v1 whitelist.
Consequences
Operator sandbox policy.
Verification anchors
Action registry docs.
-
Update on use
Context
Stale cache.
Decision
Compare cache on every use when online.
Consequences
Update prompts.
Verification anchors
Mock HTTP test.
-
Yanked warning
Context
Yank policy.
Decision
Warn on yanked; optional continue flag.
Consequences
Registry alignment.
Verification anchors
Yank API test.
- Contracts and edge cases Normative MUST/SHOULD rules for template instantiation, updates, yanked packages, and post-actions.
- Decisions record (legacy index) Migration index pointing to per-decision ADR files under adr/.
- Design model `beskid.template.v1` schema, symbols, sources, placeholders, GUIDs, and corelib policy.
- Examples Sample `beskid.template.v1` manifests and first-party `beskid.templates.*` packages.
- FAQ and troubleshooting Common questions about Beskid templates and `beskid new`.
- Flow and algorithm End-to-end lifecycle for install, update check, and instantiate.
- Verification and traceability Tests, CI, and registry checks for template conformance.
0 revisions (git unavailable at build; counts may be empty)
No commits recorded for this path.
| Section id | Required | Found |
|---|---|---|
what-this-feature-specifies | yes | yes |
implementation-anchors | yes | yes |
Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).
Purpose and scope
Section titled “Purpose and scope”Operator and author FAQs.
Why is there no useCorelib: false?
Section titled “Why is there no useCorelib: false?”Host projects always receive corelib through toolchain resolution. Templates must not document or generate an opt-out; see design model.
How do first-party templates ship?
Section titled “How do first-party templates ship?”Only as beskid.templates.* packages on pckg. The CLI downloads them when the registry is available; it does not embed stale copies when updates exist.
Can I scaffold a compiler mod?
Section titled “Can I scaffold a compiler mod?”Yes. Template output may set type: Mod and include project.mod { ... } per Project manifest contract.
Item vs project template?
Section titled “Item vs project template?”| Kind | Command shape |
|---|---|
| Project | beskid new console -o ./MyApp |
| Item | beskid new contract -o ./Src/File.bd --project ./MyApp |
| Workspace | beskid new workspace-demo -o ./MyWs |
Template build fails at template root
Section titled “Template build fails at template root”Expected: type: Template projects are not app compile targets. Run beskid new into a scratch folder to validate.
Update message on every run
Section titled “Update message on every run”By design. Install with beskid new install <package> to refresh the cache.
Yanked template still works
Section titled “Yanked template still works”You received a warning. Prefer installing a non-yanked version; use --allow-yanked only when intentional.
Placeholder left in file
Section titled “Placeholder left in file”E1904 — a {{symbol}} was not bound. Pass --symbol or run interactive mode.
pckg page shows no API docs for my template
Section titled “pckg page shows no API docs for my template”Correct for packageKind: template. See template packages.