sysand build currently looks for README.md, CHANGELOG.md, and LICENSES/<id>.txt at hardcoded paths under the project root. Projects often want to override these — most commonly when the Git repository's README.md is a contributor-facing landing page that is not what should ship in the KPAR, and the package README lives at a separate path like PUBLIC_README.md.
Proposal: Add a [build] table to sysand.toml letting projects override these source paths or disable bundling entirely.
Proposed schema
[build]
# String → use that path; `false` → disabled; omitted → default ("README.md").
readme = "PUBLIC_README.md"
# Same shape as `readme`. Default "CHANGELOG.md".
changelog = "PUBLIC_CHANGELOG.md"
# String → look up license files in that dir; `false` → don't bundle any
# license files; omitted → default ("LICENSES").
licenses_dir = "legal/licenses"
Archive paths inside the KPAR stay canonical (README.md, CHANGELOG.md, LICENSES/<id>.txt) regardless of source path — consumers don't need to know how the author named files on disk.
Key design decisions
sysand.toml, not .project.json. .project.json is the KerML-spec interchange file embedded in the KPAR; adding a sysand-only field there pollutes a standardized surface. [build] is purely a tool-side authoring concern.
- Project-local only. A
[build] table in user-level ($XDG_CONFIG_HOME/sysand/sysand.toml) is warned about and ignored. Two contributors building the same project must produce identical KPARs; [build] describes the project's output, not user preferences. Asymmetric with [[index]]/[[project]] on purpose.
- Disable via
false. readme = false opts out entirely, with no warning regardless of what's on disk.
- Missing-file behavior is asymmetric.
readme / changelog omitted + file absent → silent skip (today's behavior, preserved).
readme / changelog set to an explicit path + file absent → warn.
licenses_dir: warn per missing license file (named by SPDX expression in .project.json's license) regardless of whether the dir was overridden — the intent comes from .project.json, not sysand.toml.
Open questions
- Should
readme = "X" + file missing be a hard error instead of a warning? An explicit path is a stronger claim of intent.
- Should we also move
--compression or other building-specific settings to this table?
sysand buildcurrently looks forREADME.md,CHANGELOG.md, andLICENSES/<id>.txtat hardcoded paths under the project root. Projects often want to override these — most commonly when the Git repository'sREADME.mdis a contributor-facing landing page that is not what should ship in the KPAR, and the package README lives at a separate path likePUBLIC_README.md.Proposal: Add a
[build]table tosysand.tomlletting projects override these source paths or disable bundling entirely.Proposed schema
Archive paths inside the KPAR stay canonical (
README.md,CHANGELOG.md,LICENSES/<id>.txt) regardless of source path — consumers don't need to know how the author named files on disk.Key design decisions
sysand.toml, not.project.json..project.jsonis the KerML-spec interchange file embedded in the KPAR; adding a sysand-only field there pollutes a standardized surface.[build]is purely a tool-side authoring concern.[build]table in user-level ($XDG_CONFIG_HOME/sysand/sysand.toml) is warned about and ignored. Two contributors building the same project must produce identical KPARs;[build]describes the project's output, not user preferences. Asymmetric with[[index]]/[[project]]on purpose.false.readme = falseopts out entirely, with no warning regardless of what's on disk.readme/changelogomitted + file absent → silent skip (today's behavior, preserved).readme/changelogset to an explicit path + file absent → warn.licenses_dir: warn per missing license file (named by SPDX expression in.project.json'slicense) regardless of whether the dir was overridden — the intent comes from.project.json, notsysand.toml.Open questions
readme = "X"+ file missing be a hard error instead of a warning? An explicit path is a stronger claim of intent.--compressionor other building-specific settings to this table?