Interface spec

App Standards and Quality Gates: Interface Spec (frappe-nix v1)

• Spec version: 1.2, 2026-10-07. This is 1.1 with two changes: every internal name is replaced by a neutral one (S33), and the standards are opt-in and profile-driven (S34–S38, §8). Appendix C lists what changed from 1.1. Appendix R is the 1.0 → 1.1 review log, and Appendix R2 the review log of this 1.2 text (31 issues, each verified, fixed or rejected with a reason). The spec covers frappe-nix v1.x, [tool.frappe-nix] schema = 1 and profile schema = 1.

• Inputs:

  • the approved internal project plan (D1–D16, Phases 1 and 1.5, §6, and §7 including the 2026-10-07 defaults). "Plan §N" below refers to that plan, never to this spec;

  • the Phase 0 track results (p0-results.json);

  • carbon_frappe on PR #53;

  • frappe-nix main at 9e63c96;

  • docusystem v0.1.0;

  • the in-progress frappe-types worktrees (feat/presets-and-jsdoc, feat/gen-doctypes-and-drift-ci).

• Audience:

  • the agents implementing frappe-nix PRs N1–N6 in parallel, and the profile repository P;

  • anyone using frappe-nix app mode, inside or outside Avunu;

  • the 12 Avunu app migrations, which are the first adopters and the worked example.

• Normative language: MUST, MUST NOT, SHOULD and MAY are used as in RFC 2119. "Render" means "produce with the template engine in §3". "The app" means a Frappe app repository in frappe-nix app mode. <app> is its Python package name, <App-hyphen> is that name with _ replaced by -, and <major> is the Frappe major (16 in the examples).

• Opted-in app. An app is opted in when its pyproject.toml has a [tool.frappe-nix] table (S35). Everything in §2–§5 applies only to opted-in apps, and within one only to the modules its resolved profile enables (§8). Without the table, frappe-init behaves exactly as it does in frappe-nix main today.

• Built-in and org values. frappe-nix itself carries only vendor-neutral values. Organisation values (publisher, contact e-mail, copyright holder, licence, brand colour, URL templates, GitHub owner, registry fork, README badges and links) come from a profile or the app's config (S37). Where this spec names an Avunu value, the text says "Avunu profile" or "Avunu fleet": those values live in Avunu/frappe-standards-profile (§8.6), not in frappe-nix.

0. Decisions this spec makes

These either settle points the plan leaves open or resolve contradictions the Phase 0 tracks found. Every later section assumes them. S1–S32 are from 1.1, reworded only where the profile model changes them; S33–S43 are new in 1.2. A decision about a module applies only while that module is enabled (§8.2).

1. Repository layout in frappe-nix, and PR ownership

1.1 Landing order

1. N3a "hook points" lands first. It is a small PR, owned by the N3 agent, that only creates seams. It MUST merge before any other N-PR is rebased for merge. Every other PR MAY start before it merges, by branching from N3a's branch.

2. Development of N1, N2, N3 (the rest), N4, N5 and N6 proceeds in parallel after that.

3. Merge order follows what each PR's acceptance tests exercise:

   Step	PRs	Why
   1	N3a	Seams, the data directory, the [tool.frappe-nix] and profile schemas, the two built-in profiles.
   2	N1 and N3, in either order	N1 needs only N3a's loaders and the resolved-config reader. N3 is the sync engine and the profile resolver everything renders through.
   3	N2 and N5, after N3	N2's managed scripts/vite-register.mjs and N5's README blocks and marketplace.json fragment render through N3's engine.
   4	N4, after N1, N3 and N5	selftest-ci runs frappe-nix sync --check (N3), frappe-test --ci (N1) and frappe-nix listing check (N5).
   5	N6	frappe-nix's own pr-policy.yml runs frappe-nix policy (N4). N6's PR may merge earlier if its policy job is temporarily non-required.
   6	tag v1.0.0	N6's first release PR is merged only after N1–N5 are in, so v1.0.0 is the first complete platform and release-1 exists.

   • The frappe-nix main ruleset (repo-policy/self/rulesets/main.json) is applied with frappe-nix repo apply only after N4 merges, because it uses N4's tool.

   • P, the Avunu org profile (Avunu/frappe-standards-profile, §8.6), is created once N3 has merged, because frappe-nix profile validate (N3) checks it. Its v1.0.0 tag is made after frappe-nix v1.0.0, against which its CI validates it.

   • App migrations in the Avunu fleet (PR A, PR B) start only after frappe-nix v1.0.0 and P's v1.0.0 are tagged (S32, S38). Apps outside Avunu opt in whenever they choose, with any profile.

Overlap rule. Only the files listed below as shared are touched by more than one PR. For each shared file, N3a creates the seam and the later PR edits only its own hunk. Everything else has exactly one owner, and a PR MUST NOT edit a file it doesn't own. If a PR needs a change in another PR's file, it states that in its PR description and the owner makes the change.

1.2 The tree

[N…] marks the owner. (shared) files list each PR's hunk.

frappe-nix/
├── version.txt                                [N3a creates "0.0.0"; N6 makes release-please own it]
├── release-please-config.json                 [N6]
├── .release-please-manifest.json              [N6]
├── committed.toml                             [N6]
├── CHANGELOG.md                               [release-please]
├── flake.nix  (shared)
│     N3a: three new flake=false inputs (marketplace, pilot, frappe-semgrep-rules);
│          `packages`/`apps` merged with `import ./lib/standards/outputs.nix`;
│          `checks` merged with `import ./tests/standards { … }`
│     nobody else edits flake.nix
├── flake.lock                                 [N3a for the new inputs; afterwards dependabot]
├── py/frappe_nix_tools/                       Python project `frappe-nix-tools`, import name `frappe_nix_tools`,
│   │                                          console script `frappe-nix` (S10, S33); self-contained
│   ├── pyproject.toml                         [N3a]  deps: jinja2>=3.1,<4; tomlkit>=0.13 (no upper cap: the
│   │                                                  locked nixpkgs ships 0.15.0); packaging>=24.
│   │                                                  [project.scripts] frappe-nix = "frappe_nix_tools.cli:main";
│   │                                                  flit's include ships frappe_nix_tools/data/**
│   ├── frappe_nix_tools/__init__.py           [N3a]  release-please version block (N6 adds it to extra-files)
│   ├── frappe_nix_tools/cli.py                [N3a]  `frappe-nix <command>`; imports every module in commands/;
│   │                                                  `repo` is a command group (apply, audit, rollout)
│   ├── frappe_nix_tools/common/               [N3a]  repo.py, flakelock.py, pyproject.py ([tool.frappe-nix] loader),
│   │                                                  config.py (profile resolution and the merge, §8.4),
│   │                                                  known_apps.py, gh.py (thin `gh api` wrapper), report.py,
│   │                                                  pins.py (fetch a flake-locked GitHub tree into .dev-dist/pins/
│   │                                                  and verify its narHash), nar.py
│   ├── frappe_nix_tools/commands/paths.py     [N3a]  `frappe-nix data-path <rel>` (importlib.resources over
│   │                                                  frappe_nix_tools/data), `frappe-nix pin-path <input>` for any locked
│   │                                                  GitHub input: frappe-nix's (frappe-semgrep-rules, marketplace,
│   │                                                  pilot), the app's own (frappe, erpnext, …) or `standards-profile`
│   ├── frappe_nix_tools/commands/config.py    [N3a]  `frappe-nix config <key>` (prints a resolved value, §8.4)
│   ├── frappe_nix_tools/data/                 everything sync, listing and the hooks read at run time (S10):
│   │   ├── profiles/minimal.toml              [N3a creates both in full from §8.5; then N3; others ask N3]
│   │   ├── profiles/recommended@1.0.toml      [N3a, then N3]  frozen once v1.0.0 is tagged; a later MINOR that
│   │   │                                              changes `recommended` adds recommended@1.<minor>.toml (S42)
│   │   ├── tsconfig/base.json                 [N3]   the inline TypeScript preset (`typescript.preset = "inline"`, §2.9)
│   │   ├── schema/tool-frappe-nix.schema.json [N3a; N3 extends it, others ask N3]
│   │   ├── schema/profile.schema.json         [N3a; N3 extends it, others ask N3]
│   │   ├── known-apps.json                    [N3a]  (frappe, erpnext, hrms, payments only; §2.1)
│   │   ├── manifest.d/core.json               [N3]
│   │   ├── manifest.d/assets.json             [N2]   (scripts/vite-register.mjs)
│   │   ├── manifest.d/ci.json                 [N4]
│   │   ├── manifest.d/marketplace.json        [N5]
│   │   ├── templates/**                       [N3]   except templates/.github/** [N4], templates/marketplace/** [N5],
│   │   │                                              templates/scripts/vite-register.mjs [N2]
│   │   ├── readme/*.md.j2                     [N5]
│   │   ├── node-locks/version-16/{frappe/ui,erpnext/banking,hrms/frontend,hrms/roster}/{yarn.lock,source.json} [N3]
│   │   ├── semgrep/test-correctness.yml       [N4]   (carbon_frappe's semgrep/test-correctness.yml)
│   │   ├── ci/nightly.sh                      [N4]   (§4.6)
│   │   └── shots/shots.d.ts                   [N5]   (copy of lib/shots/shots.d.ts; a nix check asserts equality)
│   ├── frappe_nix_tools/commands/sync.py      [N3]   `frappe-nix sync --write|--check`
│   ├── frappe_nix_tools/commands/profile.py   [N3]   `frappe-nix profile show|validate` (§5.13)
│   ├── frappe_nix_tools/commands/compat.py    [N3]
│   ├── frappe_nix_tools/commands/unchecked_js.py [N3] `frappe-nix unchecked-js --stale` (§2.9)
│   ├── frappe_nix_tools/commands/testmap.py   [N1]   plus frappe_nix_tools/bench/{testmap_probe,composition}.py [N1]
│   ├── frappe_nix_tools/commands/policy.py    [N4]
│   ├── frappe_nix_tools/commands/ratchet.py   [N4]
│   ├── frappe_nix_tools/commands/minibench.py [N4]
│   ├── frappe_nix_tools/commands/gate.py      [N4]   `frappe-nix gate lint|typecheck|marketplace` (S43, §4.2)
│   ├── frappe_nix_tools/commands/repo/{apply,audit,rollout,doctor}.py [N4]  `frappe-nix repo apply|audit|rollout|doctor`
│   ├── frappe_nix_tools/commands/listing.py   [N5]   plus frappe_nix_tools/listing/** [N5]
│   ├── frappe_nix_tools/commands/icon.py      [N5]   plus frappe_nix_tools/icon/** [N5]
│   └── tests/test_<module>.py                 [owner of <module>]
├── lib/standards/
│   ├── package.nix                            [N3a]  python314 build of py/frappe_nix_tools against the locked nixpkgs
│   │                                                  (pythonRuntimeDepsCheck stays on; a nix check builds it)
│   ├── outputs.nix                            [N3a]  reads lib/standards/tools/*.nix → {packages, apps}
│   ├── shell.nix                              [N3a]  app-mode dev-shell packages and enterShell snippet; adds
│   │                                                  `frappe-nix` only to opted-in apps' shells; exports the
│   │                                                  opt-in test (a line match, never fromTOML; S35) as
│   │                                                  `optedIn` for modules/devenv.nix
│   └── tools/
│       ├── frappe-nix.nix                     [N3a]  `frappe-nix` with git and gh on its PATH (the `repo` group needs gh)
│       └── frappe-listing.nix, frappe-icon.nix, frappe-shots.nix          [N5]
├── lib/scripts.nix  (shared)                  N3a: one line merging lib/scripts.d/*.nix; nobody else
├── lib/scripts.d/
│   ├── frappe-test.nix, frappe-rename-app.nix [N1]
│   └── frappe-demo.nix, frappe-shots.nix      [N5]
├── lib/sh/frappe-test.sh                      [N1]
├── lib/sh/app-sync.sh                         [N3]
├── lib/sh/{main.sh,app-init.sh}               [N3]   (new flags: --sync, --check, --standards, --format, --only)
├── lib/init.nix                               [N3]   (adds app-sync.sh and the frappe-nix-tools runtime input)
├── lib/rename/frappe_rename_app.py            [N1]   (ported from the Phase 0 rename-mechanics prototype)
├── lib/demo/frappe_demo.py                    [N5]
├── lib/shots/{cdp.ts,runner.ts,diff.ts,shots.d.ts,package.json,yarn.lock} [N5]
├── lib/js/esbuild-preload.js                  [N2]   (requires lib/js/vite-register.cjs)
├── lib/js/vite-register.cjs                   [N2]   the one registration implementation (S30); the managed
│                                                      scripts/vite-register.mjs is a build-time copy of it
├── lib/node-targets.nix, lib/node-locks.nix   [N2]   (the `excludeNodeTargets` option, §5.11)
├── lib/frappe-workspace.py                    [N1]   (`coverage` in the generated root's dev group; `ruff`,
│                                                      `pre-commit` and `semgrep` dropped only from an opted-in
│                                                      app-mode root whose tools/pyproject.toml pins them, S1)
├── templates/bench/pyproject.toml             [N1]   adds `coverage` and `unittest-xml-reporting` only; ruff,
│                                                      pre-commit and semgrep stay (S1, S35)
├── modules/devenv.nix  (shared)
│     N3a: app-mode `apps.frappe-init`; import of lib/standards/shell.nix
│     N1:  port offset salt (opted-in apps, or `ports.worktreeSalt = true`) and FRAPPE_NIX_PORT_OFFSET;
│          FRAPPE_NIX_CI in enterShell; nixfmt/statix/deadnix in an opted-in app-mode shell; frappe-nix.renamedApps
├── modules/nixos.nix                          [N1]   (services.frappe.sites.<site>.renamedApps)
├── templates/app/
│   └── flake.nix, .envrc, .gitignore          unchanged from frappe-nix `main` (S35). `frappe-init --app` without
│                                                      `--standards` copies exactly this, as today. N3 MUST NOT change
│                                                      these files; the opted-in forms are rendered by the engine from
│                                                      data/templates/{flake.nix.j2,envrc.j2,gitignore.block} (§2.5, §2.6)
├── repo-policy/                               vendor-neutral defaults, parameterised by the resolved config (§4.8, §4.9)
│   ├── repo-settings.json                     [N4]
│   ├── rulesets/{integration,integration-provisional,release-branch,tags}.json   [N4]
│   └── self/{repo-settings.json,rulesets/{main,release,tags}.json} [N6]   (frappe-nix's own repository)
├── .github/
│   ├── workflows/app-lint.yml, app-typecheck.yml, app-test.yml, app-marketplace.yml,
│   │   app-pr-policy.yml, app-release.yml, app-deps.yml, app-nightly.yml   [N4]   reusable (S39)
│   ├── workflows/fleet-audit.yml              [N4]   reusable (`workflow_call` only): the scorecard an org
│   │                                                  schedules from its profile repository (§5.7)
│   ├── workflows/selftest-runtime.yml         [N1]
│   ├── workflows/selftest-assets.yml          [N2]   (stock-bench Vite registration, §7)
│   ├── workflows/selftest-scaffold.yml        [N3]
│   ├── workflows/selftest-ci.yml              [N4]
│   ├── workflows/selftest-product.yml         [N5]
│   ├── workflows/check.yml  (shared)
│   │     N3a: the "offline checks" step builds `.#checks.x86_64-linux.standards-all` in addition to its list
│   │     N6:  SHA-pin actions/checkout; add a `vm-tests` boolean dispatch input (default false) and
│   │          gate the vm-tests job on `inputs.vm-tests == true` instead of on any dispatch
│   ├── workflows/pr-policy.yml                [N6]   frappe-nix's own, non-reusable `pr-policy` job (§4.10)
│   ├── workflows/release.yml                  [N6]
│   ├── workflows/dependabot-auto-merge.yml    [N6]   (SHA pin; skip rules unchanged)
│   └── dependabot.yml                         [N6]
├── tests/standards/default.nix                [N3a]  reads tests/standards/*.nix; exposes `standards-all` (linkFarm)
├── tests/standards/vendor-neutral.nix         [N3a]  the S37 check, with tests/standards/vendor-denylist.txt [N3a]
│                                                      (the denylist names org values only, never the codename; §7 N3a)
├── tests/standards/<area>.nix                 [owner of <area>] (sync, profiles, compat, ports, preload-vite,
│                                                       node-targets-docs-site, policy, ratchet, listing, icon, …)
├── tests/fixtures/standards-app/              [N3a: app sources; N3: the managed files sync renders, committed]
├── tests/fixtures/profiles/                   [N3]   an org-profile fixture (`example-org`, fictitious values, §7 N3);
│                                                      [N4] `docs-compat`, which sets the docs tool's own identifiers (§7 N4)
├── tests/fixtures/spa-app/                    [N2]   (root-level Vite config, a `portal/` SPA with no package.json,
│                                                      `[[tool.frappe-nix.typescript.spa]]` entries)
├── tests/fixtures/rename-esign/               [N1]   (hooks naming `esign.desk.bundle.js`, the matching files)
└── docs/app-standards/                        docs section "App standards and quality gates"
    ├── README.md (index, links to all pages)  [N3a]
    └── <page>.md                              [N3a creates one-line stubs; each owner fills its page:
                                                profiles.md N3, managed-files.md N3, testing.md N1, assets.md N2,
                                                ci.md N4, github.md N4, marketplace.md N5, icons.md N5,
                                                screenshots.md N5, versioning.md N6, rename.md N1]

Outside frappe-nix:

Avunu/frappe-standards-profile/                [P; owned and released by Avunu, not by any N-PR]
├── profile.toml                               the Avunu org profile (§8.6)
├── templates/                                 optional template overrides (§8.1)
├── fleet.json                                 the Avunu fleet that `frappe-nix repo … --all` iterates (§4.9)
├── resolved.snapshot.json                     `frappe-nix profile show --format json` of the fixture app (§6.4)
├── repo-policy/                               P's own settings and rulesets: main.json, release.json (`refs/heads/v*`),
│                                              tags.json, applied with `frappe-nix repo apply --policy-dir` (§5.6)
├── .github/workflows/fleet-audit.yml          caller of frappe-nix's reusable fleet-audit.yml, nightly (§5.7)
├── .github/workflows/validate.yml             on every PR: `frappe-nix profile validate profile.toml`, the snapshot
│                                              comparison, and `docusystem doctor` on a synced copy of the fixture app
├── .github/workflows/release.yml              release-please, then a REST fast-forward of `v1` (§6.4)
└── release-please config, CHANGELOG.md        tags vX.Y.Z and a moving `v1` branch (§6.4)

1.3 What each PR delivers

• N3a, hook points. It delivers:

  • the seams listed above;

  • frappe-nix --version and the command dispatcher;

  • the py/frappe_nix_tools/frappe_nix_tools/data/ layout, frappe-nix data-path, and data/known-apps.json;

  • the two built-in profiles in full (§8.5), schema/profile.schema.json, and the resolver common/config.py with frappe-nix config reading resolved values, so every later PR reads module switches the same way (§8.4);

  • the standards-vendor-neutral nix check and its denylist (S37);

  • the fixture app sources in tests/fixtures/standards-app/: an app standards_fixture with one DocType, one whitelisted function with a test, one deliberately untested whitelisted function listed in [[tool.frappe-nix.untested]], doc_events on ToDo, one scheduler job, extend_doctype_class on ToDo, demo.py, marketplace/listing.toml, the icon pair and marketplace/screenshots.ts;

  • the new flake inputs;

  • the docs stubs, under docs/app-standards/.

  It has no behaviour of its own.

• N1, runtime. It delivers:

  • frappe-test;

  • coverage scoping;

  • coverage in the bench root dev group;

  • the testmap and composition checks;

  • FRAPPE_NIX_CI;

  • nixfmt, statix and deadnix in an opted-in app-mode shell;

  • the worktree port salt and FRAPPE_NIX_PORT_OFFSET, with the documentation corrections;

  • frappe-rename-app (code and site halves) and the renamedApps and replacedApps NixOS and devenv options;

  • the shell-checks stage of frappe-test --ci;

  • ruff, pre-commit and semgrep dropped from the generated root's dev group of an opted-in app whose tools/pyproject.toml pins their replacements, and from no other root (S1);

  • selftest-runtime.yml.

  N1 MAY split the rename work into a follow-up PR, N1b.

• N2, assets. It delivers:

  • Vite manifest registration as one module, lib/js/vite-register.cjs, run by esbuild-preload.js (with an unconditional child_process wrap) and shipped to apps as the managed scripts/vite-register.mjs (S30), plus its manifest.d/assets.json fragment and the frappe-nix compat rule C8;

  • the excludeNodeTargets option in node-targets.nix and node-locks.nix (default empty; an opted-in app's flake.nix sets [ "docs-site" ] while the docs-site module is on, §5.11);

  • the tests/fixtures/spa-app/ builtBench check;

  • docs/app-standards/assets.md, which covers the <name>.bundle.[hash] naming convention, bundled_asset() in www templates and [tool.bench.assets] for pilot.

• N3, scaffold. It delivers:

  • the sync engine, including the two-phase bootstrap (S32), the retire list (S31), module gating and retraction (S36, §3.3 step 6), and template overrides (§8.1);

  • org profile resolution: the standards-profile flake input in phase A, pin-path of it in no-Nix CI, frappe-nix profile show|validate (§5.13), and docs/app-standards/profiles.md;

  • every template in manifest.d/core.json;

  • frappe-init --sync, --check and --standards <profile>; templates/app/ left unchanged, and cmd_app_init delegating to frappe-nix sync --write only for an opted-in app (S35);

  • frappe-nix compat;

  • node-lock seeding;

  • the committed managed files of the fixture app;

  • selftest-scaffold.yml.

• N4, CI. It delivers:

  • the eight reusable workflows (four gates, plus pr-policy, release, deps and nightly; S39) and the reusable fleet-audit.yml;

  • frappe-nix gate lint|typecheck|marketplace, the host-agnostic gate steps the reusable workflows call (S43);

  • the caller templates (manifest.d/ci.json), each gated by its module: ci.yml, pr-policy.yml, release.yml, deps.yml, nightly.yml, assets.yml, dependabot.yml and zizmor.yml;

  • frappe-nix policy, frappe-nix ratchet, frappe-nix minibench, frappe-nix repo apply, frappe-nix repo audit, frappe-nix repo rollout and frappe-nix repo doctor;

  • repo-policy/*.json (rulesets and repo settings; the fleet list moved to the org profile repository, §8.6);

  • selftest-ci.yml.

• N5, product tools. It delivers:

  • frappe-listing check|registry|readme;

  • frappe-icon, frappe-demo and frappe-shots;

  • the README block templates;

  • marketplace/shots.d.ts;

  • selftest-product.yml.

• N6, frappe-nix self-release. It delivers:

  • release-please for frappe-nix;

  • release.yml, which runs release-please, dispatch-ci, the release-1 fast-forward and the v* tags;

  • committed.toml;

  • SHA pins across frappe-nix's own workflows;

  • frappe-nix's own pr-policy.yml and the vm-tests dispatch input on check.yml;

  • repo-policy/self/*.json;

  • frappe-nix's dependabot commit prefixes (§6.3).

• P, the Avunu org profile (Avunu/frappe-standards-profile; owned by Avunu, outside frappe-nix's PR set). It delivers:

  • profile.toml as in §8.6, extending the frozen snapshot recommended@1.0 and setting every value Avunu relies on explicitly;

  • any template overrides Avunu wants (none are required);

  • fleet.json, the 12-app fleet list that 1.1 kept in frappe-nix, each entry with profile (§4.9);

  • a scheduled caller of frappe-nix's reusable fleet-audit.yml, holding the FRAPPE_NIX_AUDIT_TOKEN secret (§5.7);

  • a validate.yml that runs frappe-nix profile validate from the frappe-nix release it targets, compares frappe-nix profile show --format json on a copy of the fixture app with the committed resolved.snapshot.json (so a frappe-nix release that changes any Avunu value fails P's CI), and runs docusystem doctor on that synced copy;

  • release-please releases (tags vX.Y.Z, moving branch v1) with a release.yml that runs release-please and then fast-forwards v1 by REST PATCH, with GitHub Actions (integration 15368) as the only bypass actor on v* branches (§6.4);

  • its own repo-policy/ (main.json, release.json on refs/heads/v*, tags.json on refs/tags/v*, as frappe-nix's repo-policy/self/ with the v* ref instead of release-*), applied with frappe-nix repo apply --policy-dir repo-policy --repo Avunu/frappe-standards-profile once N4 has merged.

  P is small and has no frappe-nix code. Nothing in frappe-nix depends on it: frappe-nix's own tests use the fictitious tests/fixtures/profiles/example-org profile.

1.4 Seam interfaces (N3a)

What N3a's seams accept, so each later PR adds files without editing the seam.

frappe-nix pin-path <input> reads --lock, by default the nearest flake.lock at or above the current directory without leaving the git work tree (so an app in a subdirectory, like frappe-nix's tests/fixtures/standards-app, reads its own), falling back to the work tree root's. It prints the Nix store path when the tree the lock's narHash implies is already in the store, and otherwise fetches it into .dev-dist/pins/<name>-<rev>/ beside that lock: a github node from codeload, a gitlab node from the GitLab API archive (host defaults to gitlab.com), a git node by git clone --filter=blob:none and a checkout of the locked rev. FRAPPE_NIX_FETCH_TOKEN, when set, is sent as Authorization: Bearer (for git, through http.extraHeader); without it a 401, 403 or 404 exits 3 with the hint to set it. A tree already in .dev-dist/pins is reused only after its NAR hash is recomputed and matches the lock; otherwise it is refetched (no stamp file is trusted, since .dev-dist sits in the app checkout, where a PR could commit any tree under that name). A locked owner, repo or host that is not a name, a git url that is not an https, http, ssh or file URL with a path, or a rev that is not a 40-hex SHA, exits 2 before anything is fetched or written. frappe-nix's own pins (frappe-semgrep-rules, marketplace, pilot) are read only through the lock's frappe-nix node (the root's inputs only in frappe-nix's own lock, which has no frappe-nix input), so a root input of the same name never shadows them, and each must lock github:frappe/semgrep-rules, frappe/marketplace or frappe/pilot respectively (case-insensitively); any other repository exits 2. standards-profile is read only from the root's inputs. Any other input is the root's own, else frappe-nix's. FRAPPE_NIX_PIN_URL (with {host}, {owner}, {repo}, {rev}) replaces a tarball URL, for mirrors and tests. frappe-nix config <key> reads --pyproject, by default the nearest pyproject.toml found the same way, resolves it (§8.4), takes dotted keys (tests.setup, modules.ssort, profile.name), prints a list one item per line, a boolean as true/false, and a table as one line of JSON (--json prints any value as JSON); on an app without [tool.frappe-nix] it exits 2 with the opt-in hint.

2. What an app gets: the managed-file contract

This section applies to opted-in apps only (S35). What an app gets is decided by its resolved configuration, so §8 (profiles and modules) is the companion to read first: every file below names the module that enables it and the profile values it reads. Values shown are the recommended ones unless a section says otherwise.

2.1 [tool.frappe-nix]: the app's parameters

[tool.frappe-nix] lives in the app's pyproject.toml and is app-owned: sync creates it once (only on opt-in, S35), never rewrites it, and validates it against frappe_nix_tools/data/schema/tool-frappe-nix.schema.json. Unknown keys are errors (exit 2).

The table holds two kinds of key:

• App keys, which only an app can set: the top-level keys below and the [[…]] lists. A profile that sets one is exit 2.

• Module tables ([tool.frappe-nix.<module>]) and [tool.frappe-nix.org], which have the same shape as in a profile (§8.1). The app's values are the last layer of the merge (§8.4): an app switches a module on or off, or changes one parameter, by writing just that key.

[tool.frappe-nix]
schema = 1                                   # required
profile = "recommended"                      # optional; "minimal" when absent (S35). A built-in name ("minimal",
                                             # "recommended", or a frozen snapshot "recommended@1.0", S42), an org
                                             # profile flake URL ("github:<owner>/<repo>[/<ref>]", "gitlab:…",
                                             # "git+https://…"), or an in-repo profile "./<dir>" (§8.3)
frappe-major = 16                            # required. Drives every version-<major> string, range and branch
siblings = ["erpnext", "hrms"]               # bench apps besides frappe, in install order. Each is a key of
                                             # known-apps.json (or of a profile's or this table's [known-apps]),
                                             # "<owner>/<repo>" for any app on GitHub, or an object (below).
                                             # Default when created: hooks.required_apps, in order
# siblings = ["erpnext", { repo = "example/shared_lib", branch = "main", range = ">=2.0.0,<3.0.0" }]
#                                            # object form: any of repo, flake-url (gitlab:/git+https:), branch,
#                                            # range, desk_global; unset fields come from the matching known-apps rule
repo = "example/my_app"                      # optional; "<owner>/<repo>" (or "<host>/<group>/…/<repo>" off GitHub).
                                             # Default: from origin (§2.2)
integration-branch = "develop"               # optional; any branch name. Default: "develop" under
                                             # releases.branching = "develop+version", "main" under "main+tags",
                                             # whether or not releases is on. `--standards` writes origin's default
                                             # branch here when it differs from that default (S41)
retire-keep = []                             # paths exempt from every retire rule (§2.4.1)
site = "carbon-theme.localhost"              # optional; default "<App-hyphen>.localhost"
nightly-suites = []                          # shell commands nightly runs inside the dev shell with the site up,
                                             # e.g. ["node scripts/test-tables.ts"]; env FRAPPE_SITE_URL,
                                             # FRAPPE_ADMIN_PASSWORD and FRAPPE_NIX_ARTIFACT_DIR are set (§4.6)
generated = []                               # globs of tracked generated files, e.g. ["<app>/public/js/generated/**",
                                             # "<app>/public/js/job_timeclock/types.ts", "components.d.ts"].
                                             # Fed into the prek global exclude, oxfmt and oxlint ignorePatterns, and
                                             # the validate_copyright exclude (§2.14). Their freshness is the app's
                                             # job, through shell-checks or ci:typecheck
build = false                                # true: the app's `build` script is a real build step even though no Vite
                                             # config, nested frontend or SPA exists (carbon's patch-assets/audits)
shell-checks = []                            # commands that need the dev shell and a git-clean result afterwards, e.g.
                                             # ["yarn -s generate-types"]; run by `frappe-test --ci` (§5.1 stage 8b)
frappe-node-modules = false                  # true: typecheck installs frappe's node_modules under FRAPPE_PATH (§4.2)

[[tool.frappe-nix.untested]]                 # module tests: testmap exemptions; shrink-only (S24)
target = "standards_fixture.api.legacy"      # dotted path of a target (§5.1.1)
reason = "Removed in 16.2; kept for old kiosk bundles"   # ≥ 10 characters

[[tool.frappe-nix.coverage-omit]]            # module tests: extra coverage omit globs; shrink-only (R7), amber in A8
glob = "timeclock/www/job_timeclock_legacy/*"
reason = "Legacy kiosk page, replaced by job_timeclock in 16.3"     # ≥ 10 characters

[[tool.frappe-nix.unchecked-js]]             # module typescript (check-js on): desk/web JS files excluded from
path = "esign/public/js/controls/upload.js"  # strict checkJs; shrink-only (R6), amber in A7. A path, not a glob;
reason = "Pre-typing legacy control; JSDoc pass tracked in #41"     # it must be a tracked .js file; ≥ 10 characters

[[tool.frappe-nix.override-doctype-class]]   # module metadata: A.3 allow-list; every override_doctype_class
doctype = "Version"                          # hook needs an entry
reason = "Must replace, not extend: …"       # ≥ 20 characters

# Module tables. Every key is optional here; the profile supplies the rest (§8.5). Shown: the app-only
# parameters each module has, plus two examples of overriding a profile value.

[tool.frappe-nix.ssort]
enable = true                                # example: switch on a module the profile leaves off

[tool.frappe-nix.org]
publisher = "Example Apps Ltd"               # example: an org value for this app only (S37)

[tool.frappe-nix.dev-shell]                  # app-only flake parameters (§2.5); custom inputs go in its local region
systems = ["x86_64-linux", "aarch64-linux", "aarch64-darwin", "x86_64-darwin"]   # flake systems
extra-substituters = []                      # appended to nixConfig.extra-substituters
extra-trusted-public-keys = []               # appended to nixConfig.extra-trusted-public-keys
frappe-nix-url = ""                          # "" = github:Avunu/frappe-nix/release-<N>. Any flake URL (a fork, a
                                             # mirror, a tag or a rev); see §2.5 for what CI then needs

[tool.frappe-nix.known-apps."example/shared_lib"]   # optional; same shape as a profile's [known-apps] (§8.1)
repo = "example/shared_lib"
branch = "main"
range = ">=2.0.0,<3.0.0"

[tool.frappe-nix.tests]
setup = []                                   # steps before the app's tests. Each is "module:<dotted test module>"
                                             # (bench run-tests --module) or "execute:<dotted callable>".
                                             # Default when empty: "module:erpnext.tests.bootstrap_test_data" if
                                             # erpnext is a sibling, else "execute:frappe.utils.install.complete_setup_wizard"
js-coverage-min = 50                         # node:test line-coverage minimum; only used when test/unit/ exists

[tool.frappe-nix.releases]
bootstrap-sha = "3c33bb4b…"                  # optional; rendered into release-please-config.json

[tool.frappe-nix.pilot-assets]
enable = false                               # true → managed .github/workflows/assets.yml and the release dispatch

[tool.frappe-nix.test-utils]
track-overrides = false                      # true → the test_utils track_overrides hook (needs HASH:/REPO: annotations)

[tool.frappe-nix.typescript]                 # app-only parameters (the profile sets enable, strict-extras, check-js)
browser = true                               # false: no tsconfig.browser.json even when public/**/*.ts is tracked
browser-include = []                         # replaces the default browser include (§2.9)
web-include = []                             # globs of JS under the package that run on web pages, not the desk
                                             # (e.g. "esign/public/js/web/**"): moved from desk to web in tsc and oxlint
paths = {}                                   # compilerOptions.paths, in tsconfig.base.json
exclude = []                                 # appended to every project's exclude. Only non-source paths: an entry
                                             # matching a tracked .js/.ts/.vue file under the package is exit 2
                                             # (use unchecked-js or an spa entry)
audit-consumer = false                       # true: typecheck runs `frappe-types audit-consumer --strict` (§4.2)

[[tool.frappe-nix.typescript.spa]]           # a Vue/Vite SPA that lives at the root or inside the package and has no
root = "portal"                              # package.json of its own. "." for the repo root (timeclock)
include = ["portal/src/**"]                  # its sources; removed from the browser, desk and web projects
tsconfig = "portal/tsconfig.json"            # app-owned; MAY extend another SPA's app-owned config (portal's
                                             # "../tsconfig.json" when an SPA owns the root), never a managed file
check = "vue-tsc --noEmit -p portal/tsconfig.json"   # run by `typecheck` and chained into scripts.check

[tool.frappe-nix.js.oxlint]
ignore = []                                  # appended to ignorePatterns
globals = {}                                 # merged into the desk-JS override's globals
overrides = []                               # appended; each {files=[…], rules={…}, globals={…}}.
                                             # While js.locked-rules is true it MUST NOT name the locked rules
                                             # (typescript/no-explicit-any, typescript/ban-ts-comment,
                                             # typescript/consistent-type-imports) or change categories (exit 2)

[tool.frappe-nix.js.oxfmt]
ignore = []                                  # appended to ignorePatterns

[tool.frappe-nix.stylelint]
globs = []                                   # default: discovered "<app>/public/**/*.scss" when any exist

A [[…]] list belongs to the module named in its comment. While that module is off, the list is ignored and not validated, and its ratchet doesn't run.

How the two SPA layouts in the fleet are declared:

# erpnext_taskview: desk Vue in public/js built by the root vite.config.ts, plus portal/ (no package.json)
[[tool.frappe-nix.typescript.spa]]
root = "."
include = ["erpnext_taskview/public/js/**"]
tsconfig = "tsconfig.json"                   # app-owned, so the managed solution is tsconfig.solution.json
check = "vue-tsc --noEmit -p tsconfig.json"
[[tool.frappe-nix.typescript.spa]]
root = "portal"
include = ["portal/src/**"]
tsconfig = "portal/tsconfig.json"            # keeps "extends": "../tsconfig.json"
check = "vue-tsc --noEmit -p portal/tsconfig.json"

# timeclock: vite.config.ts and tsconfig.json at the root, sources in the package
[[tool.frappe-nix.typescript.spa]]
root = "."
include = ["timeclock/public/js/timeclock/**", "timeclock/public/js/job_timeclock/**"]
tsconfig = "tsconfig.json"
check = "vue-tsc --noEmit -p tsconfig.json"

frappe_nix_tools/data/known-apps.json (N3a) holds the template for each known sibling. {n} is the major and {n1} is the major plus one. It names only Frappe's own apps and one generic rule for any GitHub-hosted app; a profile's [known-apps] table, and then the app's [tool.frappe-nix.known-apps], add or override entries with the same shape (§8.1, §8.4). The generic rule assumes the Frappe convention (version-{n} branches, major-tracking versions). A sibling on another convention (a main-branch, semver shared library) is declared with the object form in siblings or a known-apps entry, and every check that compares a sibling's branch or range (C3, C4, L3) uses that resolved value.

{
  "frappe":   { "repo": "frappe/frappe",   "branch": "version-{n}", "range": ">={n}.0.0,<{n1}.0.0", "desk_global": null },
  "erpnext":  { "repo": "frappe/erpnext",  "branch": "version-{n}", "range": ">={n}.0.0,<{n1}.0.0", "desk_global": "erpnext" },
  "hrms":     { "repo": "frappe/hrms",     "branch": "version-{n}", "range": ">={n}.0.0,<{n1}.0.0", "desk_global": "hrms" },
  "payments": { "repo": "frappe/payments", "branch": "version-{n}", "range": ">=0.0.1,<1.0.0",       "desk_global": null },
  "*/*":      { "repo": "{owner}/{name}",  "branch": "version-{n}", "range": ">={n}.0.0,<{n1}.0.0", "desk_global": null }
}

For an <owner>/<repo> sibling, the app name is the repo name. The flake input name is the app name. The flake URL is github:<owner>/<repo>/<branch>, or the object's flake-url (gitlab:<group>/<repo>/<branch>, git+https://<host>/<path>?ref=<branch>) for a sibling hosted elsewhere. The required_apps spelling is "<owner>/<repo>" (D6). The frappe-dependencies key is the bare app name. A bare name that is in none of known-apps.json, the profile's [known-apps] and the app's [tool.frappe-nix.known-apps] is exit 2 ("unknown sibling; write it as /"). The Avunu profile adds no entries: its siblings are written Avunu/<repo> and use the generic rule.

2.2 Discovered facts (never declared)

Sync computes these from git ls-files (tracked files only), so the result is the same on every machine. --check recomputes them, so adding a first .ts file, for example, shows up as drift until sync is run.

2.3 Template context

Every Jinja template (StrictUndefined; files end in .j2) receives this context:

app, app_hyphen, dist (pyproject [project].name), repo, title, tagline (listing → hooks app_title/app_description),
frappe = {major, next, branch: "version-<major>", preset: "version-<major>", range},
siblings = [{name, input, flake_url, branch, range, desk_global, required: bool}],   # required = in hooks.required_apps
site, cfg (= the resolved configuration, §8.4: app keys plus every module table, defaults applied),
modules (= {<module>: bool}, the resolved `enable` of each module after the dependency rules of §8.2),
org (= cfg.org, with copyright-holder defaulted to publisher), profile = {name, source, rev},
branches = {integration: <integration-branch>, release: "version-<major>" | null},   # S41; release from releases.branching
gates = [enabled gate names, in the order pr-policy, lint, typecheck, test, marketplace],   # §4.2
discover (§2.2), frappe_nix = {rev, version, major, owner, name}, floors (§2.4), app_type

profile.source is "builtin" or the org profile's flake URL, and profile.rev its locked revision (empty for a built-in). No template renders either into a file, so a profile release changes only the files whose content changes (§3.6). branches is computed even when releases is off, because dependabot's target-branch and the CI triggers use it: branches.integration is always [tool.frappe-nix] integration-branch (§2.1), and branches.release is version-<major> only while releases is on with develop+version, else null.

2.4 Inventory

Every file below is listed in a manifest.d/*.json fragment. Each entry has the form {path, template, strategy, module, when, uses, floors?, overridable?}:

• module is the module (§8.2) that enables the entry. The entry is live only when modules[<module>] is true and when is true. module may be a list, meaning any of them (the shared infrastructure files: .pre-commit-config.yaml and tools/).

• when is a Python expression over the context (for example "discover.scss"), "True" when the module alone decides.

• uses lists the profile values (org.* and module parameters) the template reads. It is documentation the engine checks: a template that reads a cfg/org key missing from uses fails the N3 nix check standards-manifest, and a live entry whose uses names an empty org value is exit 2 naming it (S37).

• overridable: true lets an org profile replace the template (§8.1).

Files whose entry isn't live MUST NOT exist. Sync deletes them (and retracts merged keys) as §3.3 step 6 says; otherwise --check reports exit 1 "file should not exist".

Merged files. pyproject.toml and package.json are touched by several modules. Each managed key or table belongs to one module and is managed only while that module is on (§2.8, §2.12). The file itself is "live" while any of its key groups is.

These are not managed, but are checked or tolerated:

• docs/ and docs-site/ are owned by the app's docs tool (docusystem in the Avunu fleet). Its workflows (docusystem's docs.yml and docs-publish.yml) are left alone, but zizmor and actionlint lint them when workflow-lint is on.

• nix/uv.lock and nix/node-locks/** belong to relock.

• CHANGELOG.md belongs to release-please.

• semgrep/*.yml is the app's own extra rules, which lint runs.

• nix/local.nix is the app's flake-parts module.

2.4.1 Retired files (S31)

manifest.d/core.json carries a retire list (N3 owns it; N4 adds the workflow rules). Each rule belongs to the module that replaces the function it retires, and applies only while that module is on: an app that doesn't enable releases keeps its own release workflow, one without dependabot keeps its own auto-merger, and one without ci keeps every workflow. An org profile adds rules of the same shape with [[retire]] (§8.1), and an app exempts any path from every rule with [tool.frappe-nix] retire-keep. Sync deletes every tracked match of an applying rule. --check reports each one as exit 1 with the problem legacy file. Audit row A9 evaluates the same list, through frappe-nix sync --check --format json, so the two can't diverge.

Name-only rules are not built in: a file name says nothing about what a workflow does, so check.yml and version-branch-guard.yml, whose jobs moved to ci.yml in the Avunu fleet, are retired by the Avunu profile's [[retire]] entries (§8.6), not by frappe-nix. A file that matches but has app-specific content worth keeping is still deleted unless it is in retire-keep; the PR diff shows it. Retiring is a one-way step, so the adoption PR (Avunu fleet: PR A) is the PR that carries these deletions.

2.5 flake.nix (whole)

Module dev-shell (every opted-in app, including minimal). Parameters (app-only, [tool.frappe-nix.dev-shell]): systems, extra-substituters, extra-trusted-public-keys, frappe-nix-url. py/frappe_nix_tools/frappe_nix_tools/data/templates/flake.nix.j2. The output MUST be byte-stable under nixfmt (an acceptance test checks this). An app that has not opted in keeps the flake.nix that templates/app/ gave it, untouched (S35).

Where an app's own Nix goes:

• Extra inputs go in the local region inputs, inside the inputs attribute set. Its content is kept verbatim; a name that collides with a managed input (frappe-nix, nixpkgs, frappe, standards-profile, a sibling) is exit 2.

• Outputs (packages, overlays, nixosModules, checks, extra dev-shell settings) go in nix/local.nix, a flake-parts module imported below; it can define perSystem and flake.* outputs and reads the extra inputs through inputs.

• Systems and binary caches are the parameters above.

• The frappe-nix source. frappe-nix-url replaces github:Avunu/frappe-nix/release-<N> with any flake URL: a tag (…/v1.2.3), a rev, a fork or a mirror. Phase A then re-locks only when the locked node's original differs from that URL (§3.3), so a pin is never undone. A GitHub fork is supported everywhere: the caller workflows' uses: and the no-Nix install read the locked owner/repo (§2.2 frappe_nix, §3.7, §4.1). A non-GitHub URL (git+https:) works for the dev shell and sync, and is exit 2 while ci is on, because a GitHub uses: can't name it. The skew rule (§3.7) compares the locked rev with the rev the running frappe-nix-tools was built from, so any pin works as long as the two agree.

First opt-in. When an app opts in (--standards) and its existing flake.nix has no managed header, sync compares it with what templates/app/flake.nix renders for the app. If they differ, sync exits 2, prints the diff of what would be replaced, and names the three places above; --force replaces it anyway. The same rule applies to .envrc. (Avunu fleet: PR A passes --force where an app's flake predates the template, after its diff is reviewed.)

# frappe-nix:managed — generated by frappe-nix (`frappe-init --sync`); edit only inside the frappe-nix:local region.
# App-specific Nix goes in nix/local.nix, a flake-parts module imported below when it exists.
{
  description = "{{ app }}: {{ title }}";

  inputs = {
    frappe-nix.url = "{{ cfg['dev-shell']['frappe-nix-url'] or 'github:Avunu/frappe-nix/release-' ~ frappe_nix.major }}";
    nixpkgs.follows = "frappe-nix/nixpkgs";
    frappe = {
      url = "github:frappe/frappe/{{ frappe.branch }}";
      flake = false;
    };
{%- if profile.source != "builtin" %}
    standards-profile = {
      url = "{{ profile.source }}";
      flake = false;
    };
{%- endif %}
{%- for s in siblings %}
    {{ s.input }} = {
      url = "{{ s.flake_url }}";
      flake = false;
    };
{%- endfor %}
    # frappe-nix:local-begin inputs
    # frappe-nix:local-end inputs
  };

  nixConfig = {
    extra-substituters = [ "https://devenv.cachix.org"{% for u in cfg['dev-shell']['extra-substituters'] %} "{{ u }}"{% endfor %} ];
    extra-trusted-public-keys = [
      "devenv.cachix.org-1:w1cLUi8dv3hnoSPGAuibQv+f9TZLr6cv/Hm9XgU50cw="
{%- for k in cfg['dev-shell']['extra-trusted-public-keys'] %}
      "{{ k }}"
{%- endfor %}
    ];
  };

  outputs =
    { frappe-nix, ... }@inputs:
    frappe-nix.lib.mkFlake { inherit inputs; } (
      { lib, ... }:
      {
        imports = [
          frappe-nix.flakeModules.default
        ]
        ++ lib.optional (builtins.pathExists ./nix/local.nix) ./nix/local.nix;

        systems = [
{%- for sys in cfg['dev-shell'].systems | sort %}
          "{{ sys }}"
{%- endfor %}
        ];

        perSystem =
          { pkgs, ... }:
          {
            formatter = pkgs.nixfmt;
            frappe-nix = {
              enable = true;
              siteName = "{{ site }}";
              app = {
                enable = true;
                frappeVersion = "{{ frappe.preset }}";
                inherit (inputs) frappe;
{%- if modules["docs-site"] %}
                excludeNodeTargets = [ "docs-site" ];   # §5.11
{%- endif %}
                siblings = [
{%- for s in siblings %}
                  {
                    name = "{{ s.name }}";
                    src = inputs.{{ s.input }};
                  }
{%- endfor %}
                ];
              };
            };
          };
      }
    );
}

standards-profile is the org profile's input (S38, §8.3). Nothing in the app's Nix evaluation reads it; it is in flake.nix so that flake.lock pins the profile revision the rendered files came from. Sync writes this file and locks it in phase A (§3.3), before anything reads flake.lock. nix is required for --sync; --check never runs it and reports missing lock nodes as exit 1.

2.6 .envrc (whole) and the .gitignore block

Module dev-shell. Profile values: none. These are the opted-in forms, rendered from data/templates/envrc.j2 and data/templates/gitignore.block; templates/app/.envrc and templates/app/.gitignore stay as they are in main for apps that have not opted in.

.envrc (local region envrc, for dotenv, exports and other direnv lines; it is sourced after use flake):

# frappe-nix:managed — generated by frappe-nix; edit only inside the frappe-nix:local region.
use flake . --no-pure-eval
# frappe-nix:local-begin envrc
# frappe-nix:local-end envrc

The .gitignore managed block (between the existing # >>> frappe-nix >>> markers) is the templates/app/.gitignore body plus:

/.dev-dist/
*.tsbuildinfo
.ruff_cache/
__pycache__/

2.7 .editorconfig (whole + local region)

Module editorconfig. Profile values: editorconfig.indent ("tab", Frappe's convention, in recommended; or "space", which renders indent_style = space with indent_size = 4) and editorconfig.line-length (110). This fixes two bugs in carbon_frappe's copy: YAML and Nix can't use tabs.

# frappe-nix:managed — generated by frappe-nix (`frappe-init --sync`); edit only inside the frappe-nix:local region.
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{py,js,mjs,cjs,ts,mts,vue,css,scss,html,jinja,toml,json,jsonc,sh}]
indent_style = {{ cfg.editorconfig.indent }}
indent_size = 4
max_line_length = {{ cfg.editorconfig["line-length"] }}

[*.{yml,yaml,nix}]
indent_style = space
indent_size = 2

# frappe's exporter: 1-space JSON, no final newline, for everything under the package
[{{ app }}/**.json]
indent_style = space
indent_size = 1
insert_final_newline = false

[*.md]
trim_trailing_whitespace = false

# frappe-nix:local-begin editorconfig
# frappe-nix:local-end editorconfig

2.8 package.json (json-merge)

Live while any module with a key group below is on. Profile values: org.license, org.publisher, metadata.package-type, metadata.package-manager, metadata.node-engine, typescript.preset, tests.js-coverage-min. No module needs another module's key group: js, typescript, stylelint and vite-register need only that package.json exists, which any of them makes true.

Sync creates package.json if it's missing, as {"name": "<App-hyphen>", "version": "<__version__ or 0.1.0>", "private": true, "description": <tagline>}, plus "license": <org.license> and "author": <org.publisher> when those org values are set. After that, only the keys below are managed, each only while its module is on. Every other key is app-owned (for example dependencies, build, codegen, ci:lint, ci:typecheck). version is owned by release-please (module releases), except once: when sync seeds .release-please-manifest.json, it first sets version to __version__ (taskview has 1.0.0 against 0.0.1, timeclock 0.0.0 against 0.0.1), because __version__ is what the registry reads.

When a module turns off, sync removes its keys whose values still equal what it would render (a toolchain devDependencies entry counts as equal when its range is ^<floor> or higher), and leaves any other value as app-owned, with a warning (§3.3 step 6).

Forbidden (exit 2), each only while the named module is on:

• (metadata) a build script when none of these holds: discover.vite, a nested frontend, an SPA entry, or [tool.frappe-nix] build = true (carbon sets it for its patch-assets, audits and ai-chat build). frappe's esbuild runs every app's build, so a stray one runs on every bench. Conversely, build = true without a build script is exit 2.

• (js, tool oxc) eslint*, prettier*, @typescript-eslint/* or eslint-config-* in any dependency map;

• (any) scripts keys starting with frappe-nix:, which are reserved.

2.9 TypeScript configs (whole, JSONC with header)

Module typescript. Profile values: typescript.strict-extras (the three extra compiler options in tsconfig.base.json; true in recommended), typescript.check-js (whether the desk and web projects exist at all: false in recommended, true in the Avunu profile) and typescript.preset (below). With check-js off, desk and web JS is still linted by oxlint when js is on, but not type-checked, and [[tool.frappe-nix.unchecked-js]], R6 and A7's amber are inactive.

Every file starts with // frappe-nix:managed — generated by frappe-nix (\frappe-init --sync`); do not edit. Customise via [tool.frappe-nix.typescript].`

The preset dependency. With typescript.preset = "frappe-types" (the recommended value), the compiler presets and the Frappe type declarations come from the npm package frappe-types (≥ 16.5.0; MIT; source github.com/Avunu/frappe-types, maintained by the frappe-nix authors): frappe-types/tsconfig/base.json, frappe-types/tsconfig/desk-js.json, frappe-types/global and frappe-types/web. 16.5.0, the first release with the presets and frappe-types/web, is on npm (published 2026-10-07). It is a third-party open-source dependency like oxlint, not an org value: nothing of Avunu's is rendered into the app, and dependabot moves it in the toolchain group. With typescript.preset = "inline", tsconfig.base.json carries the compiler options itself (from frappe-nix-tools' data/tsconfig/base.json, a copy of the preset's options) instead of extends, the frappe-types devDependency is not managed, and the frappe-types/* entries are dropped from types. check-js, audit-consumer and the gen-doctypes freshness step need the Frappe declarations, so each of them with preset = "inline" is exit 2.

The solution file is named discover.solution: tsconfig.json, or tsconfig.solution.json when an SPA owns the root tsconfig.json (taskview, timeclock). Sync never writes over an SPA's config. It lists only the projects that exist, in the order browser, scripts, test, desk, web:

{
	"files": [],
	"references": [{ "path": "./tsconfig.browser.json" }, { "path": "./tsconfig.scripts.json" }, { "path": "./tsconfig.test.json" }, { "path": "./tsconfig.desk.json" }, { "path": "./tsconfig.web.json" }]
}

tsconfig.base.json holds the app-level strictness the frappe-types preset leaves out (the compilerOptions keys below other than paths are omitted when typescript.strict-extras is false). With preset = "inline", extends is absent and the preset's options are rendered into compilerOptions first:

{
	"extends": "frappe-types/tsconfig/base.json",
	"compilerOptions": {
		"noUnusedLocals": true,
		"noUnusedParameters": true,
		"noImplicitReturns": true,
		"paths": { /* [tool.frappe-nix.typescript].paths; key omitted when empty */ }
	}
}

tsconfig.browser.json:

{
	"extends": "./tsconfig.base.json",
	"compilerOptions": { "composite": true, "types": ["frappe-types/global"], "allowImportingTsExtensions": true },
	"include": ["<app>/public/js/**/*.ts", "<app>/public/js/**/*.d.ts", "types/**/*.d.ts"],   // or browser-include
	"exclude": ["node_modules", "<app>/public/dist", /* spa_globs, cfg.generated, typescript.exclude */]
}

tsconfig.scripts.json:

{
	"extends": "./tsconfig.base.json",
	"compilerOptions": { "composite": true, "types": ["node"], "allowImportingTsExtensions": true },
	"include": ["scripts/**/*.ts", "marketplace/**/*.ts", "ci/**/*.ts"],
	"exclude": ["node_modules"]
}

tsconfig.test.json:

{
	"extends": "./tsconfig.base.json",
	"compilerOptions": { "composite": true, "types": ["node", "frappe-types/global"], "allowImportingTsExtensions": true },
	"include": ["test/**/*.ts", "<app>/public/js/**/*.ts", "scripts/lib/**/*.ts"],
	"exclude": ["node_modules", "<app>/public/dist"]
}

tsconfig.desk.json checks uncompiled desk JS with JSDoc (D5), only when typescript.check-js is true:

{
	"extends": "frappe-types/tsconfig/desk-js.json",
	"compilerOptions": { "composite": true },
	"include": ["<app>/**/*.js", "types/doctypes.d.ts", "types/<app>.augment.d.ts"],
	"exclude": ["node_modules", "**/*.bundle.js", "**/public/dist/**", "<app>/www/**", "**/web_form/**",
	            "<app>/templates/**", /* each nested frontend dir, spa_globs, typescript.web-include,
	            cfg.generated, each unchecked-js path, typescript.exclude */]
}

tsconfig.web.json covers web form and www scripts, and the files typescript.web-include moves out of the desk (esign's public/js/web/**, which uses frappe.web_form, frappe.ready and frappe.form_dirty):

{
	"extends": "frappe-types/tsconfig/desk-js.json",
	"compilerOptions": { "composite": true, "types": ["frappe-types/web"] },
	"include": ["<app>/www/**/*.js", "<app>/**/web_form/**/*.js", "<app>/templates/**/*.js",
	            /* typescript.web-include */ "types/doctypes.d.ts", "types/<app>.augment.d.ts"],
	"exclude": ["node_modules", "**/public/dist/**", /* spa_globs, cfg.generated, each unchecked-js path,
	            typescript.exclude */]
}

The desk and web projects are rendered from the same file sets as discover.desk_js and discover.web_js, and so are the oxlint overrides (§2.10). Both are rendered only when their file set is non-empty after the exclusions, so an app can't hit TS18003 ("no inputs") by excluding everything.

Migrating to strict checkJs (when an app turns typescript.check-js on). The frappe-types track measured esign at 274 errors, timeclock at about 238 (plus 4,056 in a committed legacy bundle), jailbreak 59, postgrid 36 and jwt_auth 6. The adoption PR (Avunu fleet: PR B) lists each file it can't fix yet in [[tool.frappe-nix.unchecked-js]] with a reason. That list is rendered into the desk and web excludes and ratchets like untested: R6 lets it only shrink. An entry naming a file that is no longer tracked is stale (frappe-nix compat C9, exit 1). An entry whose file no longer has any error is also stale: the typecheck job runs frappe-nix unchecked-js --stale (N3), which runs tsc -p once over a generated temporary project that includes every listed file and fails naming each listed file with zero diagnostics. Audit row A7 is amber while the list is non-empty. // @ts-nocheck stays forbidden (typescript/ban-ts-comment). A committed build output such as timeclock/www/job_timeclock_legacy/index.js belongs in cfg.generated or should be deleted, not listed as unchecked.

SPAs ([[tool.frappe-nix.typescript.spa]]) keep their own app-owned tsconfig. Their globs are removed from the browser, desk and web projects and from the desk-globals override; typecheck runs each check. Nested frontends with a package.json work as before: typecheck runs their own typecheck script.

• types/doctypes.d.ts, if the app has it, is the output of frappe-types gen-doctypes. It is committed and checked for freshness in typecheck (§4.2).

• App symbols on the frappe namespace. An app declares the members it adds to frappe (taskview's frappe.views.TasksView, esign's frappe.ui.form.ControlFontSelect and frappe.esign_context, jailbreak's frappe.ui.merge_records, timeclock's frappe.ui.form.show_workday_bulk_add) in exactly one file, types/<app>.augment.d.ts, as declare global { namespace frappe.<sub> { … } } augmentations. Each member carries a // app-owned: <reason> comment on the line before it. App-owned, never managed.

• Hand-written frappe globals are an frappe-nix compat C7 failure (exit 1), which is plan §6 row "no hand-written frappe globals". C7 matches redeclarations only: declare (var|let|const) frappe, interface Window { containing a frappe member, declare namespace frappe anywhere, and any namespace frappe augmentation outside types/<app>.augment.d.ts or without its // app-owned: comments. taskview's public/js/types/frappe.d.ts and timeclock's public/js/timeclock/env.d.ts are deleted in their PR B, and their app-owned members move to the augment file.

2.10 .oxlintrc.json (whole JSON, no comments) and .oxfmtrc.jsonc (whole)

Module js with js.tool = "oxc" ("none" renders neither file and no format/lint scripts). Profile values: js.oxlint.categories (the categories object below is the recommended value), js.locked-rules (when true, the three typescript/* rules below are "error" and an app override may not touch them; when false they are ordinary rules an app may override), js.format-width (110) and js.format-tabs (true), plus the app's js.oxlint and js.oxfmt lists.

.oxlintrc.json. The desk and web overrides are generated from the same file sets tsc uses (§2.2), not from fixed globs:

• <desk-files> is discover.desk_js rendered as a sorted list of paths (oxlint matches literal paths as globs). A new desk file is therefore drift until sync runs, which is the same rule tsconfig already follows.

• <web-files> is discover.web_js, likewise.

• Files in spa_globs get neither override; their globals come from their own imports.

{
	"$schema": "./node_modules/oxlint/configuration_schema.json",
	"plugins": ["typescript", "unicorn", "oxc", "import"],
	"categories": { "correctness": "error", "suspicious": "error", "perf": "warn", "pedantic": "off" },   // js.oxlint.categories
	"env": { "builtin": true, "es2024": true, "browser": true },
	"rules": {
		"typescript/no-explicit-any": "error",
		"typescript/ban-ts-comment": "error",
		"typescript/consistent-type-imports": "error",
		"no-console": ["warn", { "allow": ["error", "warn"] }],
		"import/no-cycle": "off",
		"no-underscore-dangle": "off",
		"unicorn/consistent-function-scoping": "off",
		"unicorn/no-array-sort": "off"
	},
	"ignorePatterns": ["<app>/public/dist/**", ".frappe-nix/**", ".dev-dist/**", "nix/**", "docs-site/**", "types/doctypes.d.ts"
	                   /* + cfg.generated + [tool.frappe-nix.js.oxlint].ignore */],
	"overrides": [
		{ "files": ["scripts/**", "marketplace/**", "ci/**", "test/**"], "env": { "node": true },
		  "rules": { "no-console": "off", "no-await-in-loop": "off", "import/no-unassigned-import": "off" } },
		{ "files": ["<app>/public/js/*.bundle.ts", "<app>/public/js/*.bundle.js"], "rules": { "import/no-unassigned-import": "off" } },
		{ "files": <desk-files>, "globals": { "frappe": "readonly", "__": "readonly", "cur_frm": "readonly",
		  "cur_list": "readonly", "locals": "readonly", "$": "readonly", "jQuery": "readonly", "moment": "readonly"
		  /* + "<desk_global>": "readonly" for each sibling with one, + [tool.frappe-nix.js.oxlint].globals */ } },
		{ "files": <web-files>, "globals": { "frappe": "readonly", "__": "readonly", "$": "readonly",
		  "jQuery": "readonly" /* + [tool.frappe-nix.js.oxlint].globals */ } }
		/* + [tool.frappe-nix.js.oxlint].overrides */
	]
}

An override whose file list is empty is omitted.

.oxfmtrc.jsonc:

// frappe-nix:managed — generated by frappe-nix (`frappe-init --sync`); do not edit. Customise via [tool.frappe-nix.js.oxfmt].
// Tabs and 110 columns are frappe's convention. Anything .gitignore'd is skipped without being listed.
{
	"$schema": "./node_modules/oxfmt/configuration_schema.json",
	"useTabs": true,      // js.format-tabs
	"printWidth": 110,    // js.format-width
	"ignorePatterns": [
		// frappe's exporter writes every JSON under the package and rewrites it on export
		"<app>/**/*.json",
		"nix/**",
		"docs-site/**",
		"docs/screenshots/**",
		// written by release-please
		"CHANGELOG.md",
		".release-please-manifest.json",
		// generated by frappe-types gen-doctypes
		"types/doctypes.d.ts"
		/* + cfg.generated + [tool.frappe-nix.js.oxfmt].ignore */
	]
}

Every whole-strategy text file that oxfmt formats (YAML, TOML, Markdown, JSONC) MUST already be in oxfmt's output form, whether or not the app enables js. N3 and N4 acceptance tests run oxfmt --check over a freshly rendered fixture. An app whose own formatter (prettier or biome, added through the repos local region or outside prek) reformats these files is not in drift: while js.tool isn't "oxc", --check compares YAML, JSON, JSONC and TOML whole files semantically, and sync leaves a file alone when it is semantically equal to the rendered one (§3.2).

2.11 .stylelintrc.json (json-merge, only when discover.scss)

Module stylelint. Profile values: none. Managed keys:

• extends: exactly ["stylelint-config-standard-scss"];

• ignoreFiles: MUST contain "<app>/public/dist/**".

Any other key (rules, more ignoreFiles entries) is app-owned.

2.12 pyproject.toml (toml-merge)

The engine is tomlkit, which preserves comments and order. Each managed group belongs to one module and is managed only while that module is on; when the module turns off, sync removes the group's keys that still hold the rendered values (§3.3 step 6). Groups: [project] requires-python/dynamic, [build-system] (only with metadata.build-backend = "flit"; with "any" it is app-owned, so setuptools, hatchling and poetry-core work) and [tool.bench.frappe-dependencies] → metadata; [tool.ruff*] → python-lint; [tool.ty*] → python-types; [tool.coverage*] → tests (tests.coverage.enable); [tool.vulture] and [tool.test_utils.*] (Appendix I, N3) → test-utils. Profile values: python-lint.line-length, .select, .ignore, .typing-modules, .quote-style, .indent-style; python-types.error-on-warning; tests.coverage.initial-floor.

Managed exact. Sync sets these and --check compares their values. Shown with the recommended values.

[project]                                  # metadata
requires-python = ">=3.14"                 # from the frappe-nix preset for version-<major>
dynamic = ["version"]                      # must contain "version"

[build-system]                             # metadata.build-backend = "flit" only
requires = ["flit_core >=3.4,<4"]
build-backend = "flit_core.buildapi"

[tool.bench.frappe-dependencies]           # exactly {"frappe"} ∪ hooks.required_apps (bare names); values from known-apps.json
frappe = ">=16.0.0,<17.0.0"
erpnext = ">=16.0.0,<17.0.0"

[tool.ruff]                                # python-lint
line-length = 110                          # python-lint.line-length
target-version = "py314"

[tool.ruff.lint]
select = ["F", "E", "W", "I", "UP", "B", "RUF", "SIM", "C4", "PIE", "PERF", "T20"]   # python-lint.select
ignore = ["E501", "W191"]                  # python-lint.ignore
typing-modules = ["frappe.types.DF"]       # python-lint.typing-modules

[tool.ruff.format]
quote-style = "double"                     # python-lint.quote-style
indent-style = "tab"                       # python-lint.indent-style
docstring-code-format = true

[tool.ty.environment]                      # python-types
python-version = "3.14"

[tool.ty.src]
include = ["<app>"]

[tool.ty.terminal]
error-on-warning = false                   # python-types.error-on-warning (the Avunu profile sets true)

[tool.coverage.run]                        # tests
omit = ["*/tests/*", "*/test_*.py", "*/patches/*"]   # + each [[tool.frappe-nix.coverage-omit]].glob, in order.
                                                    # Patches match testmap's own **/patches/** exclusion: a fresh
                                                    # install marks them complete without running them.

[tool.coverage.report]
show_missing = true
skip_covered = true
precision = 1
exclude_also = ["if TYPE_CHECKING:", "raise NotImplementedError", "@(abc\\.)?abstractmethod"]

App-owned, but validated. Sync never touches these. Each rule applies while the module in brackets is on.

Forbidden (exit 2), while the module in brackets is on:

• [python-lint] tool.ruff.lint.extend-select, extend-ignore, ignore beyond python-lint.ignore, unfixable, tool.ruff.lint.isort (the app changes the rule set through [tool.frappe-nix.python-lint], not around it);

• [python-types] tool.ty.rules with any value other than "error", and tool.ty.overrides;

• [tests] tool.coverage.run.source and tool.coverage.run.relative_files, which belong to frappe-test;

• [metadata with build-backend = "flit"] [tool.poetry] (D6 uses flit);

• [metadata with build-backend = "flit"] requirements.txt existing anywhere tracked (retired under the Appendix I rule).

2.13 <app>/__init__.py (blocks)

Module releases (the block is what release-please's generic updater rewrites). Profile values: none. The side-effect rule below (L5) belongs to listing.

# x-release-please-start-version
__version__ = "16.1.0"
# x-release-please-end

• Only comment lines are allowed outside the block, such as test_utils' copyright stamp and its blank line. A docstring and any statement count as side effects (marketplace rule): exit 1.

• The version value is app-owned (release-please writes it). Sync only converts carbon_frappe's trailing # x-release-please-version form into the block form and keeps the value.

• Whitelisted functions or any other code in __init__.py (jailbreak's assert_capability and check_capability) move to <app>/api.py in the adoption PR (Avunu fleet: PR B). The old dotted paths stay reachable through an override_whitelisted_methods shim in hooks.py for one minor release, as for renames (§5.10).

• frappe-nix compat (C5, module releases) requires: __version__ = package.json version = manifest ".". The registry parses the line __version__ = "…" (add_release.py dynamic_version), so nothing may follow the closing quote.

2.14 .pre-commit-config.yaml (whole + local region repos; third-party revs are floors)

Live while any hook module is on (§2.4). This is the rendered form with every module on (the Avunu profile); {% if %} marks the parts that depend on discovered facts. Each hook, or each remote repo: block, is additionally wrapped in {% if modules[<module>] %} as this table gives, and a remote block whose hooks are all off is omitted with its rev::

default_install_hook_types lists commit-msg only when commits is on.

# frappe-nix:managed — generated by frappe-nix (`frappe-init --sync`); edit only inside the frappe-nix:local region.
#
# Run by prek (`prek install` once per clone; the dev shell does it) and by CI's `lint` job:
#   uv run --frozen --project tools prek run --all-files --show-diff-on-failure
# A hook that rewrites a file fails CI. ruff, ty, committed, zizmor, actionlint and shellcheck are pinned
# by tools/uv.lock; oxfmt, oxlint and stylelint by package.json; ssort, pre-commit-hooks and test_utils by the
# `rev:`s below. dependabot moves all three.
default_install_hook_types: [pre-commit, commit-msg]
default_stages: [pre-commit]
default_language_version:
  python: python3.14
fail_fast: false
exclude: ^(nix/|\.frappe-nix/|docs-site/|CHANGELOG\.md$|types/doctypes\.d\.ts${% for g in cfg.generated %}|{{ g | glob_to_regex }}{% endfor %})

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: check-merge-conflict
      - id: check-ast
      - id: check-toml
      - id: check-yaml
        args: [--allow-multiple-documents]
      - id: check-json
        exclude: ^(tsconfig(\.[a-z]+)?\.json|\.vscode/.*)$
      - id: debug-statements
      - id: detect-private-key
      - id: check-added-large-files
        args: [--maxkb={{ cfg.hygiene["max-file-kb"] }}]
        exclude: ^docs/screenshots/

  # Definitions before their first use; nothing else reordered. ssort can't resolve names
  # imported inside the class-body `if TYPE_CHECKING:` block frappe generates, so only
  # <doctype>/<doctype>.py controllers are excluded. Tests and helpers in doctype folders are sorted.
  - repo: https://github.com/bwhmather/ssort
    rev: 0.17.0
    hooks:
      - id: ssort
        exclude: '/doctype/([^/]+)/\1\.py$'

  - repo: local
    hooks:
      - id: ruff-isort
        name: ruff import sorter
        language: system
        entry: uv run --frozen --project tools ruff check --select I --fix
        types: [python]
      - id: ruff-check
        name: ruff check
        language: system
        entry: uv run --frozen --project tools ruff check --fix
        types: [python]
      - id: ruff-format
        name: ruff format
        language: system
        entry: uv run --frozen --project tools ruff format
        types: [python]
      - id: oxfmt
        name: oxfmt
        language: system
        entry: yarn -s oxfmt
        pass_filenames: false
        always_run: true
      - id: oxlint
        name: oxlint
        language: system
        entry: yarn -s oxlint
        pass_filenames: false
        types_or: [javascript, jsx, ts, tsx, vue]
{% if discover.scss %}
      - id: stylelint
        name: stylelint
        language: system
        entry: yarn -s stylelint {{ scss globs, quoted }}
        pass_filenames: false
        types: [scss]
{% endif %}
      - id: zizmor
        name: zizmor
        language: system
        entry: uv run --frozen --project tools zizmor --config .github/zizmor.yml .github/workflows .github/dependabot.yml
        pass_filenames: false
        files: ^\.github/
      - id: actionlint
        name: actionlint
        language: system
        entry: uv run --frozen --project tools actionlint
        pass_filenames: false
        files: ^\.github/workflows/
      - id: shellcheck
        name: shellcheck
        language: system
        entry: uv run --frozen --project tools shellcheck --severity=warning
        types: [shell]
        exclude: ^\.envrc$
      - id: frappe-nix-compat
        name: frappe-nix compat (versions, ranges, majors)
        language: system
        entry: sh -c 'if command -v frappe-nix >/dev/null; then exec frappe-nix compat; fi; echo "frappe-nix-compat skipped (frappe-nix not on PATH; CI runs it)" >&2'
        pass_filenames: false
        always_run: true
        verbose: true
      - id: committed
        name: committed (conventional commit)
        language: system
        entry: uv run --frozen --project tools committed --commit-file
        stages: [commit-msg]
      - id: frappe-nix-commit-msg
        name: no major bump through a commit message
        language: system
        entry: sh -c 'if command -v frappe-nix >/dev/null; then exec frappe-nix policy --commit-msg-file "$1"; fi; echo "frappe-nix-commit-msg skipped (frappe-nix not on PATH; pr-policy runs it)" >&2' --
        stages: [commit-msg]

  # agritheory/test_utils: selected hooks only (S19). sql_registry/sql_rewriter abort the run,
  # mypy is replaced by ty, and validate_*_dependencies crash outside a bench, so none of those are here.
  - repo: https://github.com/agritheory/test_utils
    rev: v1.30.1
    hooks:
      - id: validate_frappe_project
      - id: validate_patches
        args: [--app, {{ app }}]
      - id: static_analysis
        args: ["."]
      - id: validate_doctype_python_types
      - id: validate_copyright
        args: [--app, {{ app }}]
        # Never stamp a managed file (its header is line 1) or a generated one (its freshness diff would fail).
        exclude: ^(docs/|docs-site/|marketplace/shots\.d\.ts$|types/doctypes\.d\.ts$|scripts/vite-register\.mjs$|tsconfig[^/]*\.json${% for g in cfg.generated %}|{{ g | glob_to_regex }}{% endfor %})
      # Bench-aware: silent no-ops outside a bench. CI runs them in a mini-bench (`frappe-nix minibench`).
      - id: validate_customizations
        stages: [manual]
      - id: clean_customized_doctypes
        stages: [manual]
      # Nightly only (jscpd through npx, needs the network).
      - id: check_code_duplication
        stages: [manual]
{% if cfg["test-utils"]["track-overrides"] %}
      - id: track_overrides
        args: [--app, {{ app }}, --base-branch, {{ frappe.branch }}]
{% endif %}

  # frappe-nix:local-begin repos
  # frappe-nix:local-end repos

Generated files. cfg.generated reaches every tool that would otherwise rewrite or stamp a generated file: the global exclude above (so ruff, ssort and test_utils skip it), validate_copyright's exclude, and the oxfmt and oxlint ignorePatterns. glob_to_regex is a fixed filter in the engine (** → .*, * → [^/]*, anchored at the end with $). The managed files whose first line is the managed header are excluded from validate_copyright by name, so sync and the stamp never rewrite each other.

zizmor scope (workflow-lint). zizmor audits .github/workflows and .github/dependabot.yml. Every rendered dependabot entry therefore carries a cooldown (§2.17), which zizmor's dependabot-cooldown audit requires. docusystem's docs*.yml are audited too.

Floor semantics (S9). The renderer emits rev: {{ rev(url, floor) }}. When the existing file has a rev for the same repo: URL that compares ≥ the floor, that rev is kept. Revs compare with packaging.version after stripping a leading v. The floors are v6.0.0, 0.17.0 and v1.30.1.

frappe-nix is on PATH in an opted-in app's dev shell (N3a shell.nix) and in CI (§4.1). A commit made outside the dev shell (a GUI git client, an editor's commit button) skips the two frappe-nix hooks with a warning instead of failing: CI's lint (compat, through the same hook with frappe-nix installed) and pr-policy (the commit-message rules) still enforce them. The uv run, yarn and committed hooks need uv and node on PATH, as any prek setup does.

2.15 committed.toml and tools/pyproject.toml (whole)

committed.toml (module commits; profile values commits.allowed-types and commits.subject-length, shown with the recommended values, which are frappe's commitlint types) is carbon_frappe's file with the managed header. The second comment paragraph depends on releases.version-scheme:

# frappe-nix:managed — generated by frappe-nix (`frappe-init --sync`); do not edit.
{% if cfg.releases["version-scheme"] == "frappe-major" %}
# Conventional commits. `fix:` → patch, `feat:` → minor. There is no way to bump the major: it is the
# Frappe major, and `frappe-nix policy` refuses `!` and BREAKING CHANGE (S12).
{% else %}
# Conventional commits. `fix:` → patch, `feat:` → minor, `!` or BREAKING CHANGE → major.
{% endif %}
style = "conventional"
allowed_types = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "refactor", "revert", "style", "test", "deprecate"]
subject_length = 100
line_length = 0
subject_capitalized = false
subject_not_punctuated = true
imperative_subject = false
no_wip = true
no_fixup = true
merge_commit = false

tools/pyproject.toml (live while any module with a tool here is on, §2.4). dependencies is the union of the enabled modules' tools, sorted: prek whenever .pre-commit-config.yaml is live, ruff (python-lint), ty (python-types), semgrep (semgrep), zizmor and actionlint-py (workflow-lint), shellcheck-py (shell-lint), committed (commits). Shown with all of them:

# frappe-nix:managed — generated by frappe-nix (`frappe-init --sync`); do not edit.
# Python-side tooling. Pinned by tools/uv.lock (dependabot uv, directory /tools). Run as
# `uv run --frozen --project tools <tool>`. A separate project because app mode's workspace lock is nix/uv.lock.
[project]
name = "{{ app_hyphen }}-tools"
version = "0"
requires-python = ">=3.14"
dependencies = ["actionlint-py", "committed", "prek", "ruff", "semgrep", "shellcheck-py", "ty", "zizmor"]

[tool.uv]
package = false

Lock floors (S9). --check reads tools/uv.lock and requires, for each tool that is in dependencies:

A lock below a floor is drift (exit 1). Sync fixes it with uv lock --project tools --upgrade-package <pkg>.

2.16 release-please-config.json (whole JSON) and manifest (seed)

Module releases (releases.tool = "release-please", the only tool in v1). Profile values: releases.version-scheme (only in the bullets below) and releases.tag-prefix ("v" or ""; include-v-in-tag is true exactly when it is "v", and the tag ruleset, assets trigger, guard and audit rows use the same prefix). The branch release-please targets is branches.integration, passed by app-release.yml (§4.4), not written here. When readme is on under main+tags, extra-files also lists { "type": "generic", "path": "README.md" }, so the release PR moves the installation line's version (§2.19).

{
	"$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
	"include-v-in-tag": true,
	"include-component-in-tag": false,
	"separate-pull-requests": true,
	"bootstrap-sha": "<[tool.frappe-nix.releases].bootstrap-sha; key omitted when unset>",
	"packages": {
		".": {
			"release-type": "node",
			"package-name": "<App-hyphen>",
			"changelog-path": "CHANGELOG.md",
			"extra-files": [{ "type": "generic", "path": "<app>/__init__.py" }]
		}
	}
}

• .release-please-manifest.json is seeded as {".": "<__version__>"}. In the same step sync sets package.json version to __version__, so C5 and L4 hold from the first sync. From then on both are owned by release-please.

• Under version-scheme = "frappe-major": for the first release, the adoption PR's (Avunu fleet: PR B's) last commit ends with the footer Release-As: <major>.0.0, and npx release-please release-pr --dry-run --target-branch <that PR's branch> must propose <major>.0.0 before merging. The PR is then merged with gh pr merge --squash --body-file <f> whose last paragraph is that same footer, so the squash commit on the integration branch carries it as a trailing footer (S11). If the release PR still proposes another version, C1 fails it. frappe-nix policy --pr still checks the major in any Release-As it finds in that PR's commits.

• Under version-scheme = "semver" nothing special happens: release-please proposes the next version from the commits, and C1 does not apply.

2.17 .github/dependabot.yml (whole + local region updates)

Module dependabot. Profile values: dependabot.ecosystems (one switch per ecosystem below), dependabot.cadence ("weekly" in recommended, "daily" in the Avunu profile) and dependabot.cadence-overrides (per ecosystem), dependabot.cooldown-days (3), and, when docs-site is on, docs-site.action-patterns (the docs-actions group and auto-merge patterns), docs-site.cooldown-exclude-actions (the github-actions entry's cooldown exclude, exact names) and docs-site.package-names (the /docs-site npm entry's cooldown exclude). All three are empty in recommended; the Avunu profile sets ["Avunu/docusystem*"], ["Avunu/docusystem"] and ["@avunu/docusystem"]. The group takes glob patterns, while a docs tool's own check may expect an exact name in the cooldown exclude (docusystem's doctor tests excludes.includes("Avunu/docusystem")), so the two are separate parameters. Each entry is rendered only when its ecosystem switch is on (and, as before, its {% if %} fact holds). {{ cadence(<ecosystem>) }} is the override for that ecosystem, else dependabot.cadence; a weekly cadence renders day: monday.

# frappe-nix:managed — generated by frappe-nix (`frappe-init --sync`); edit only inside the frappe-nix:local region.
# Every entry targets {{ branches.integration }} and commits as chore(deps)/chore(deps-dev), so no bump cuts a release.
{% if modules.ci %}
# deps.yml decides what merges automatically (§4.5).
{% endif %}
version: 2
updates:
{% if cfg.dependabot.ecosystems["github-actions"] %}
  # One entry for /, which is also the entry a docs tool scaffolds. Separate groups,
  # so a docs or pilot bump never holds up the rest.
  - package-ecosystem: github-actions
    directory: /
    target-branch: {{ branches.integration }}
    schedule: { interval: {{ cadence("github-actions") }} }
    cooldown: { default-days: {{ cfg.dependabot["cooldown-days"] }}{% if docs_cooldown_exclude %}, exclude: {{ docs_cooldown_exclude | tojson }}{% endif %} }
    commit-message: { prefix: chore, include: scope }
    labels: [dependencies]
    # frappe-nix's reusable workflows move only through `frappe-nix repo rollout` and `frappe-init --sync` (S5)
    ignore:
      - dependency-name: {{ frappe_nix.owner }}/{{ frappe_nix.name }}
    groups:
{% if docs_actions %}
      docs-actions:             # needs-review: a merge publishes the docs site with the new workflow code
        patterns: {{ docs_actions | tojson }}
{% endif %}
{% if modules["pilot-assets"] %}
      pilot:                    # needs-review: builds release assets
        patterns: ["frappe/pilot*"]
{% endif %}
      actions:
        patterns: ["*"]
        exclude-patterns: {{ (docs_actions + pilot_patterns) | tojson }}   # key omitted when empty
{% endif %}
{% if cfg.dependabot.ecosystems.npm and package_json_live %}
  - package-ecosystem: npm
    directory: /
    target-branch: {{ branches.integration }}
    schedule: { interval: {{ cadence("npm") }} }
    cooldown: { default-days: {{ cfg.dependabot["cooldown-days"] }} }
    commit-message: { prefix: chore, include: scope }
    labels: [dependencies]
    groups:
      toolchain:
        patterns: [oxlint, oxfmt, typescript, frappe-types, "@types/node", "stylelint*"]
        update-types: [minor, patch]
      runtime:
        patterns: ["*"]
        update-types: [minor, patch]
{% for d in discover.nested_frontends %}
  - package-ecosystem: npm
    directory: /{{ d }}
    target-branch: {{ branches.integration }}
    schedule: { interval: {{ cadence("npm") }} }
    cooldown: { default-days: {{ cfg.dependabot["cooldown-days"] }} }
    commit-message: { prefix: chore, include: scope }
    labels: [dependencies]
    groups:
      {{ d }}: { patterns: ["*"], update-types: [minor, patch] }
{% endfor %}
{% if discover.docs_site and modules["docs-site"] %}
  # docs-site/: a merge publishes the site, so deps.yml never merges these automatically
  - package-ecosystem: npm
    directory: /docs-site
    target-branch: {{ branches.integration }}
    schedule: { interval: weekly }
    cooldown: { default-days: 7{% if docs_packages %}, exclude: {{ docs_packages | tojson }}{% endif %} }
    commit-message: { prefix: chore, include: scope }
    labels: [dependencies]
    groups:
      docs-site-packages: { patterns: ["*"] }
{% endif %}
{% endif %}
{% if cfg.dependabot.ecosystems.uv and tools_live %}
  - package-ecosystem: uv
    directory: /tools
    target-branch: {{ branches.integration }}
    schedule: { interval: {{ cadence("uv") }} }
    cooldown: { default-days: {{ cfg.dependabot["cooldown-days"] }} }
    commit-message: { prefix: chore, include: scope }
    labels: [dependencies]
    groups:
      tools: { patterns: ["*"], update-types: [minor, patch] }
{% endif %}
{% if cfg.dependabot.ecosystems["pre-commit"] and precommit_has_remote_hooks %}
  - package-ecosystem: pre-commit
    directory: /
    target-branch: {{ branches.integration }}
    schedule: { interval: {{ cadence("pre-commit") }} }
    cooldown: { default-days: {{ cfg.dependabot["cooldown-days"] }} }
    commit-message: { prefix: chore, include: scope }
    labels: [dependencies]
    groups:
      hooks:
        patterns: ["*"]
        exclude-patterns: ["*agritheory/test_utils*"]
      test-utils:               # rendered only when test-utils is on
        patterns: ["*agritheory/test_utils*"]
{% endif %}
{% if cfg.dependabot.ecosystems.nix %}
  - package-ecosystem: nix
    directory: /
    target-branch: {{ branches.integration }}
    schedule: { interval: {{ cadence("nix") }} }
    cooldown: { default-days: {{ cfg.dependabot["cooldown-days"] }} }
    open-pull-requests-limit: 5
    commit-message: { prefix: chore, include: scope }
    labels: [dependencies]
    # frappe-nix and the org profile move only through `frappe-nix repo rollout` (S5, S38): their bump can rewrite
    # workflow files, which GITHUB_TOKEN can't push. Dependabot moves frappe and the siblings, which never touch one.
    ignore:
      - dependency-name: frappe-nix
{% if profile.source != "builtin" %}
      - dependency-name: standards-profile
{% endif %}
    groups:
      flake-inputs: { patterns: ["*"] }
{% endif %}
{% if discover.gitmodules and cfg.dependabot.ecosystems.gitsubmodule %}
  - package-ecosystem: gitsubmodule
    directory: /
    target-branch: {{ branches.integration }}
    schedule: { interval: {{ cadence("gitsubmodule") }} }
    cooldown: { default-days: {{ cfg.dependabot["cooldown-days"] }} }
    commit-message: { prefix: chore, include: scope }
    labels: [dependencies]
{% endif %}
  # frappe-nix:local-begin updates
  # frappe-nix:local-end updates

docs_actions, docs_cooldown_exclude and docs_packages are docs-site.action-patterns, docs-site.cooldown-exclude-actions and docs-site.package-names when docs-site is on, else empty lists; pilot_patterns is ["frappe/pilot*"] when pilot-assets is on. package_json_live, tools_live and precommit_has_remote_hooks say whether those files are live and whether the pre-commit config has a remote repo: block. The github-actions ignore names the repository the app locks frappe-nix from (Avunu/frappe-nix, or a fork set through dev-shell.frappe-nix-url), read from flake.lock; frappe-nix's own repository is the one org name a built-in template may contain (S37).

The rendered output is expanded to block style by oxfmt's rules; the template stores the oxfmt-formatted result. Major npm and uv updates arrive as individual PRs, because the groups only take minor and patch updates. deps.yml labels them needs-review.

• Docs-tool compatibility. For docusystem (Avunu profile), the /docs-site npm entry and the github-actions entry for / are the entries docusystem init scaffolds, with the cooldown exclusions its doctor checks (@avunu/docusystem and Avunu/docusystem, which come from the profile's docs-site values). docusystem upgrade only adds an entry when none exists for that ecosystem and directory, so on a synced repo it writes nothing. The acceptance test is in N4 (§7), run with the docs-compat fixture profile, whose three docs-site values are exactly the Avunu profile's; P's own CI runs docusystem doctor against the real Avunu profile (§1.3 P).

• Dependabot ignores for nix. If the nix ecosystem doesn't honour ignore for a flake input, deps.yml still never auto-merges a PR that moves the frappe-nix or standards-profile lock node: relock-plan detects it, and the auto-merge job comments <input> moves through frappe-nix repo rollout and closes the PR.

2.18 .github/zizmor.yml (whole)

Module workflow-lint. Profile values: none.

# frappe-nix:managed — generated by frappe-nix (`frappe-init --sync`); do not edit.
# Every `uses:` is hash-pinned with a version comment. dependabot moves third-party pins;
# `frappe-init --sync` moves Avunu/frappe-nix's.
rules:
  unpinned-uses:
    config:
      policies:
        "*": hash-pin

2.19 README generated blocks (N5; blocks, only when discover.has_listing)

Module readme (needs listing; off in recommended). Profile values: org.license, org.copyright-holder, org.email, org.support-url, org.dev-docs-url, org.repo-url, org.readme.badges, org.readme.links, readme.install-ref. Each block template is overridable by an org profile (§8.1). A block that needs an empty org value is exit 2 naming the key (S37), except org.email and org.support-url, of which the support block needs one.

Blocks are delimited by <!-- frappe-nix:begin <name> --> and <!-- frappe-nix:end <name> -->. They are rendered by frappe-listing readme --write, which sync calls (§3.5), from frappe_nix_tools/data/readme/<name>.md.j2 or the profile's override. The required blocks, in this order, are header, compatibility, installation, support, development and license, plus the hand-written sections in between, as D15 sets out. Missing markers are an error: frappe-listing readme --check exits 2 and names the missing block.

• header: a centred <div> containing:

  • the logo <img src="<app>/public/images/<app>-logo.svg" width="80"> (only when icons is on);

  • the H1 title, and the tagline;

  • badges: CI (actions/workflows/ci.yml/badge.svg?branch=<branches.integration>, when ci is on), latest release (shields github/v/release, when releases is on and the repo is on GitHub), licence (org.license), and Frappe v<major>; then each org.readme.badges entry {label, image, link} in order;

  • a hero <picture> with a dark <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/<hero>-dark.webp"> and <img src="docs/screenshots/<hero>-light.webp" alt="<alt>">. <hero> is the shot with readme: "hero". The <picture> is omitted when there are no shots or screenshots is off.

• compatibility: a table with Frappe <major> → <branches.release or branches.integration> and each required app with its range.

• installation: Frappe Cloud marketplace text (only when listing.publish is on) plus

  bench get-app <repo URL> --branch <ref>
  bench --site <site> install-app <app>

  <repo URL> is org.repo-url with {repo} substituted (default https://github.com/{repo}; a GitLab or self-hosted organisation sets its own template). <ref> is readme.install-ref when set; otherwise branches.release under develop+version, and under main+tags the latest released tag, <tag-prefix><__version__>, never main (which holds unreleased code). The main+tags form wraps the code block in <!-- x-release-please-start-version --> and <!-- x-release-please-end -->, and README.md is a release-please extra file (§2.16), so the release PR that bumps __version__ moves this line in the same commit and the block never drifts.

• support: org.support-url (default: the repo's issues page), org.email when set, and each org.readme.links entry.

• development: nix develop (or direnv allow), prek install (when .pre-commit-config.yaml is live), frappe-test (when tests is on), and a link to org.dev-docs-url (S26).

• license: <org.license>, Copyright (c) <first-commit-year>–present <org.copyright-holder> → license.txt. <first-commit-year> is the year of git log --reverse --format=%cs | head -1, which never changes. Nothing in a rendered block depends on today's date (§3.4).

Avunu profile example: MIT, Copyright (c) 2024–present Avunu LLC → license.txt, support mail@avu.nu.

2.20 .git-blame-ignore-revs (seed + validated)

Module hygiene. Profile values: none.

Seed:

# Mass reformats (style: PRs), one squash SHA per line with its subject as a comment.
# GitHub reads this file; locally the dev shell sets blame.ignoreRevsFile.

Validation (frappe-nix compat):

• every non-comment line is <40-hex> # <subject> (two spaces before #);

• every SHA is reachable from HEAD. This is checked only when the history is available (lint has fetch-depth: 0).

In the Avunu fleet, PR B adds PR A's squash SHA. The helper frappe-nix compat --add-blame-ignore <sha> appends the line with the commit subject.

The dev shell's enterShell (N3a shell.nix) runs git config blame.ignoreRevsFile .git-blame-ignore-revs when the file exists and the setting differs.

2.21 Marketplace files (N5)

Module listing (off in recommended), and screenshots, demo and icons for the files those modules name. Profile values: org.website-url, org.docs-url (the expected URL patterns, L12, and the seed's values).

marketplace/listing.toml is app-owned and validated by frappe-listing (§5.2). The example is an Avunu fleet app:

schema = 1
title = "Carbon Theme for Frappe"          # ≤ 40 chars; third-party marks only as "… for X" / "… via X"
tagline = "IBM Carbon design for the Frappe desk, website, email, charts and tables"  # 40–80 chars, no trailing period
type = "extension"                         # application | extension | integration | utility
category = "Extensions"                    # Applications | Compliance | Developer Tools | Extensions | Integrations | Utilities
categories = ["Theme", "UI"]               # non-empty
website = "https://avunu.net/open-source/carbon_theme/"
documentation = "https://carbon-theme.avunu.net/"
apps_screen = false

[apps_screen_entry]                        # required iff apps_screen = true
route = "/app/taskview"
has_permission = "erpnext_taskview.api.has_app_permission"

[registry]                                 # optional
stars = 0
channel = "stable"

Expected URL patterns are the profile's templates, with {app} and {app_hyphen} substituted:

• website: org.website-url (Avunu profile: https://avunu.net/open-source/{app}/);

• documentation: org.docs-url (Avunu profile: https://{app_hyphen}.avunu.net/).

A value that differs is a warning, not an error (docs-and-urls track). With an empty template there is no expected pattern and L12 is skipped. sync --init-listing seeds both URLs from the templates, or leaves them as "" (which L1 then reports) when the templates are empty.

marketplace/screenshots.ts (module screenshots) is app-owned. marketplace/shots.d.ts is managed: it is the ShotSpec types (§5.5), rendered from frappe_nix_tools/data/shots/shots.d.ts, the packaged copy of lib/shots/shots.d.ts. The spec file is written as

import type { ShotSpec } from "./shots.d.ts";
export default { … } satisfies ShotSpec;

so Node's type stripping runs it with no runtime import.

marketplace/semgrep-baseline.json schema:

{ "schema": 1, "marketplace_rev": "<sha it was produced against>",
  "findings": [ { "rule": "frappe-manual-commit", "path": "erpnext_taskview/erpnext_taskview/api.py",
                  "line_sha1": "<sha1 of the stripped matched first line>", "count": 12, "reason": "…" } ] }

The baseline is a multiset (S21). (rule, path, line_sha1) is unique within the file, and count ≥ 1. L7 fails when a key is found more often than its count (new finding) or less often (the count must be lowered: stale). R3 compares counts per key, head ≤ base.

<app>/demo.py (module demo) is app-owned: setup(ctx) (§5.4). Icons (module icons) are app-owned sources: <app>/public/images/<app>-symbolic.svg, and <app>-logo.svg, which frappe-icon tile generates and which is committed.

3. The managed-file mechanism (N3)

3.1 Where the data lives

• Everything lives inside the package (S10): templates in py/frappe_nix_tools/frappe_nix_tools/data/templates/**, with .j2 meaning Jinja, and manifest fragments in py/frappe_nix_tools/frappe_nix_tools/data/manifest.d/*.json. The engine reads the union of all fragments through importlib.resources, so a uv tool install from the git subdirectory has the same data as the Nix build. The built-in profiles live beside them in data/profiles/. templates/app/ (flake.nix, .envrc, .gitignore) is left exactly as in main: frappe-init --app copies it for an app that has not opted in, and the engine never reads it.

• Org profile data (S38) comes from the locked standards-profile tree, or from the app's own tree for an in-repo profile (profile = "./<dir>"): profile.toml, and the optional templates/ overrides and [[extra-files]] templates (§8.1). For an entry with overridable: true, the engine renders <profile tree>/templates/<template> when that file exists, else the built-in template. An override of a non-overridable template is exit 2 naming it.

• A path listed in more than one fragment is a frappe-nix build error. tests/standards/sync.nix checks for it.

• A fragment entry looks like this:

{ "path": ".github/workflows/ci.yml", "template": ".github/workflows/ci.yml.j2", "strategy": "whole",
  "module": "ci", "when": "True", "uses": ["ci.test-timeout-minutes"], "overridable": false,
  "local_regions": [], "floors": {}, "header": "yaml" }

header is one of yaml|toml|shell|ini|nix (#), jsonc|ts (//), or none (plain JSON). The header is the first line or lines of the rendered output, and it is part of the byte comparison.

3.2 Strategies

Local regions (only in YAML, INI-style, shell-style and Nix files, all of which use # comments) look like this:

# frappe-nix:local-begin <name>
…kept verbatim…
# frappe-nix:local-end <name>

• The names and their order are fixed by the template.

• A missing region is treated as empty and recreated.

• An unknown region, a duplicate region or an unbalanced marker is a configuration error (exit 2).

• After merging, the result MUST still parse (YAML; Nix through nix-instantiate --parse when Nix is available) and MUST NOT redefine a managed hook id, an updates entry with the same ecosystem and directory, an EditorConfig section that's already managed, or a managed flake input. Any of these is exit 2.

Floors are expressed in the template as {{ rev("<repo-url>", "<floor>") }} and {{ pin("<owner>/<repo>/<path>", "<sha>", "<version>") }}, the latter for third-party uses: in caller files:

• pre-commit revs: the existing value is kept if its version is ≥ the floor.

• third-party SHA pins (pilot in assets.yml): the existing SHA line is always kept once present, because dependabot owns it.

• frappe-nix's own uses: (<frappe_nix.owner>/<frappe_nix.name>/.github/workflows/app-*.yml) is never a floor. It is always @<frappe_nix.rev> # v<frappe_nix.version>.

Formatting. After writing, sync runs yarn -s oxfmt <written files> when js.tool = "oxc" and node_modules/.bin/oxfmt exists, and uv run --frozen --project tools ruff format <app>/__init__.py when python-lint is on. --check compares toml-merge and json-merge files semantically, so formatting changes made by oxfmt are never drift.

3.3 frappe-init --sync and --check: the CLI

frappe-init --sync  [--standards <profile>] [--force] [--dry-run] [--skip-lock] [--only <path>[,<path>…]]
                    [--init-listing] [--frappe-version version-16] [--profile-path <dir>]
frappe-init --check [--format text|json|github] [--only …] [--expect-rev <sha>] [--profile-path <dir>]
frappe-init --app   [--standards <profile>] …                      (the existing app-mode flags)

• Both imply --app mode. Both run in the current directory, which MUST be a git work tree whose pyproject.toml [project].name names a package containing hooks.py.

• Opt-in (S35). --sync and --check on an app without [tool.frappe-nix] exit 2 with this app has not opted in to frappe-nix app standards; run frappe-init --sync --standards minimal|recommended|github:<owner>/<repo>, and write nothing. --standards <profile> creates the table with profile = "<profile>" (step 1) and is otherwise ignored when the table exists and names the same profile; naming a different one is exit 2 (edit profile instead). frappe-init --app without --standards, on an app without the table, does exactly what it does in main: it copies templates/app/ and stops. With --standards, or on an app that has the table, it copies templates/app/ with install_template keep and then runs frappe-nix sync --write.

• --profile-path <dir> reads the org profile from a local directory instead of the locked input, for profile authors. It is never rendered into flake.nix, it prints a warning on every run, and --check with it exits 3 when CI is set.

• frappe-init sources lib/sh/app-sync.sh, which execs frappe-nix sync --write|--check … from frappe-nix-tools in its runtimeInputs.

• Bootstrap (an app with no flake, or one that locks frappe-nix main), from outside any dev shell:

  nix run github:Avunu/frappe-nix/release-1#frappe-init -- --app --sync --frappe-version version-16

  with --standards <profile> added the first time. This is the single documented entry point for an adoption PR (Avunu fleet: PR A). It needs only nix and git. release-1 exists from v1.0.0 on, so migrations start after N6 tags it (S32).

• Later runs inside an app: nix run .#frappe-init -- --sync is preferred. It uses the frappe-nix from flake.lock, and the app-mode flake exposes apps.frappe-init (N3a).

• A new app: frappe-init --app alone gives today's three files; frappe-init --app --standards recommended gives those, then everything the recommended profile renders (N3).

--sync runs in two phases (S32). Each step is a no-op when there is nothing to do.

Phase A: the flake.

1. Load [tool.frappe-nix], or create it when --standards is given (otherwise exit 2, above). When creating it:

   • profile comes from --standards;

   • frappe-major comes from --frappe-version, else the existing flake.nix frappeVersion, else it is an error;

   • siblings comes from hooks.required_apps, with the existing flake siblings appended (an existing sibling whose flake URL the generic rule wouldn't produce is written in the object form, so its branch is kept);

   • integration-branch is written only when git symbolic-ref --short refs/remotes/origin/HEAD names a branch other than the branching model's default. Then resolve the profile far enough to know its source (§8.3): a built-in name or an in-repo ./<dir> needs nothing more; a flake URL is the standards-profile input.

2. Render and write flake.nix and .envrc only. On first opt-in, an existing unmanaged flake.nix or .envrc that differs from what templates/app/ renders stops here with exit 2 unless --force is given (§2.5).

3. If flake.lock is missing, its input set differs from flake.nix (this covers adding, removing or re-pointing standards-profile), or its frappe-nix node's original doesn't match the rendered URL (release-<N> for the running frappe-nix-tools' major, or dev-shell.frappe-nix-url when set): nix flake lock (moving frappe-nix in the last case). A pinned tag, rev, fork or mirror in frappe-nix-url is therefore kept on every run. The lock now holds a release-1 commit and, for an org profile, a standards-profile commit. Then read profile.toml from the locked standards-profile tree and finish resolving the configuration (§8.4); a resolution error is exit 2 before phase B writes anything. For frappe-nix's own self-tests only, FRAPPE_NIX_URL_OVERRIDE (e.g. path:$GITHUB_WORKSPACE) is passed as --override-input frappe-nix <url> to the lock step and every later nix call; it is never rendered into flake.nix, and sync refuses it unless FRAPPE_NIX_ALLOW_SKEW=1.

4. Re-read frappe_nix.rev from the new lock. If it differs from the running frappe-nix-tools' own rev (a bootstrap from a newer or older release), sync re-executes itself as nix run --no-pure-eval .#frappe-init -- --sync <same args> once, so phase B always renders with the frappe-nix-tools that the lock pins. The environment variable FRAPPE_NIX_SYNC_REEXEC=1 prevents a second re-exec.

Phase B: everything else. If yarn or uv is missing from PATH, sync re-enters through FRAPPE_NIX_CI=1 nix develop --no-pure-eval -c frappe-nix sync --write --phase b <same args> once, so the lock steps below always run.

5. Render every other live entry (module on and when true, §2.4), and apply its strategy. When this turns a module on that needs a repository setting (releases, dependabot with auto-merge), sync prints run frappe-nix repo doctor (§5.6).

6. Retract what isn't live. This is how turning a module off removes its files (S36):

   • a whole file is deleted when it still opens with its managed header and its local regions are empty (Appendix I, N3); with a non-empty local region it is left, and sync exits 2 naming the region, so local content is never lost silently;

   • a seed file is left (it is app content once seeded) and reported;

   • a blocks file has its managed blocks and markers removed;

   • in a merged file, each managed key of an off module is removed when its value still equals the rendered one, and is otherwise left as app-owned with a warning (§2.8, §2.12);

   • a caller workflow of an off gate is a whole file and is deleted like any other, which removes the gate's job (S39).

7. Delete every match of an applying retire rule (§2.4.1), except paths in retire-keep.

8. If tools/pyproject.toml changed, tools/uv.lock is missing, or a lock floor isn't met: uv lock --project tools [--upgrade-package …].

9. If a managed package.json key changed or yarn.lock is missing: yarn install --non-interactive.

10. Seed the missing nix/node-locks/<key> for each present sibling, where key ∈ {frappe/ui, erpnext/banking, hrms/frontend, hrms/roster}.

11. If the frappe-nix or a sibling lock node changed since the last relock, and --skip-lock isn't given: nix run --no-pure-eval .#relock. The last relocked state is recorded in nix/uv.lock's header comment, which relock writes.

12. If readme is on and discover.has_listing: frappe-nix listing readme --write.

13. git add -A every path written or deleted. Nothing is committed.

--dry-run prints the unified diff of steps 2, 5, 6 and 7 and the commands the other steps would run, and writes nothing. A dry run on an unbootstrapped app renders phase B against the rev phase A would lock, resolved with git ls-remote https://github.com/Avunu/frappe-nix refs/heads/release-1.

--check performs steps 1, 2, 5, 6 and 7 in memory, then validates (each item only while its module is on):

• the lock floors (step 8);

• that flake.lock contains a node for every input in flake.nix, and that the standards-profile node is locked from the URL profile names;

• that the version skew is zero (§3.7);

• the README blocks (frappe-nix listing readme --check, when installed);

• .git-blame-ignore-revs;

• the validation rules for app-owned keys (§2.12).

It never runs nix, uv or yarn, so it works in no-Nix CI. It reads an org profile through pin-path standards-profile (narHash-verified, §5.2 "Pins").

Exit codes, which both modes share:

When several apply, the highest code wins.

Output.

• text: one block per file with path, strategy, the problem, and a unified diff (--- current / +++ rendered). The last line is frappe-nix: N file(s) drifted — run \frappe-init --sync`orfrappe-nix: clean`.

• json: {"status":"clean|drift|invalid|error","frappe_nix":{"rev","version"},"profile":{"name","source","rev"},"modules":{"<module>":bool},"files":[{"path","strategy","module","problem","diff"}]}. frappe-nix repo audit consumes it.

• github: the text form plus ::error file=<path>::<problem> annotations.

3.4 Idempotency

• --sync run twice in a row MUST leave the tree byte-identical after the second run, and --check MUST exit 0 right after any --sync that exited 0.

• Rendering MUST be deterministic:

  • no timestamps and nothing derived from the current date (dates come from git history only);

  • sorted iteration wherever order isn't given by data;

  • git ls-files discovery;

  • a fixed Jinja configuration (trim_blocks=True, lstrip_blocks=True, keep_trailing_newline=True).

3.5 Parameters and app-specific values (summary)

3.6 Headers

The header names no version and no profile, so a frappe-nix or profile release only touches files whose content actually changed.

3.7 Version skew

Let rev be the frappe-nix rev in flake.lock. All of the following MUST hold:

• Every <frappe_nix.owner>/<frappe_nix.name>/.github/workflows/app-*.yml@<sha> in the caller workflows has <sha> == rev and the comment # v<frappe_nix_tools.__version__>.

• The running frappe-nix was built from rev. Nix knows this directly, because the dev shell's frappe-nix comes from the locked frappe-nix. In CI the install step records the rev, and lint passes it as --expect-rev "$FRAPPE_NIX_EXPECT_REV" (§4.1). frappe-nix sync --check is the same as frappe-init --check, and both accept --expect-rev.

If any of these fails, --check exits 3. The exceptions, the only places that set FRAPPE_NIX_ALLOW_SKEW=1:

• frappe-nix repo audit --against latest and the nightly drift job;

• frappe-nix's own self-tests: when an app-*.yml gets a non-empty frappe-nix-override, the install step exports FRAPPE_NIX_ALLOW_SKEW=1 and lint omits --expect-rev. A commit can't contain its own SHA, so the fixture's rendered callers can never match the commit under test.

4. CI: the reusable workflows and their callers (N4)

Everything in this section exists in an app only while the ci module is on (S36), and each workflow and job only while its own module is on:

The gates context list (§2.3) is the first five rows' gates that are present. The gate logic is a command, not YAML (S43). frappe-nix gate lint|typecheck|marketplace runs that gate's steps in order, each only when its module is on (it resolves the configuration itself), and exits non-zero when any step failed, after running all of them. The test gate is frappe-test --ci, which reads the same switches (§5.1). A reusable workflow therefore only checks out, installs node, uv and frappe-nix-tools, runs the gate command, and uploads its report; any other CI (GitLab CI, Woodpecker, a laptop) runs the same command after the same setup, which docs/app-standards/ci.md lists. Workflow-level steps that do need a module switch (the node cache, the frappe node_modules install) read it from frappe-nix config --github-output modules (step id cfg). The gate workflows take no input per module, and a parameter change never needs a caller change; only turning a whole gate or workflow on or off changes the rendered callers. (app-nightly.yml is the exception: its optional jobs take run-* inputs, §4.6.)

<integration> below is branches.integration (any branch name, S41), passed to each reusable workflow as the input integration-branch by the rendered caller; <release> is branches.release, empty under main+tags.

Private sources (S43). Every reusable workflow accepts the optional secret FETCH_TOKEN, which callers pass from secrets.FRAPPE_NIX_FETCH_TOKEN. When it is non-empty, the install step exports it as FRAPPE_NIX_FETCH_TOKEN, which pin-path and minibench use for authenticated fetches of a private org profile, frappe fork or sibling (§5.2 "Pins"), and the Nix setup adds access-tokens = github.com=<token> to the job's nix.conf. It needs only Contents read on those repositories. For Dependabot runs it must also be a Dependabot secret.

4.1 Conventions shared by every app-*.yml

• Third-party actions are SHA-pinned with a version comment, matching the zizmor policy "*": hash-pin. The pins below are the current ones from carbon_frappe and frappe-nix; N4 resolves actions/* to SHAs.

  • DeterminateSystems/nix-installer-action@3138316df39ed29be04236d7ffc686fa525866aa # v23 (determinate: false)

  • DeterminateSystems/magic-nix-cache-action@84c0677f58dcedf3b91f8223ce36a9ea5b3c84b7 # v15 (use-flakehub: false, diagnostic-endpoint: ""; frappe-nix self-tests only, S15)

  • astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0

  • googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0

  • dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0

  • actions/checkout, actions/setup-node, actions/cache, actions/upload-artifact and cachix/cachix-action, each @<sha> # vN.

• Checkouts always use persist-credentials: false, with no exception. The three jobs that push — relock-push and relock-upgrade (§4.5) and nightly shots (§4.6) — push to an explicit remote, git push "https://x-access-token:${GH_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" HEAD:<ref>, with GH_TOKEN: ${{ github.token }} in that step's env: only. Before pushing, each runs git diff --name-only <base>..HEAD | grep -q '^\.github/workflows/' && exit 1 (S29).

• Permissions. Each workflow sets permissions: {} at the top, and every job declares exactly what it needs.

• Environment. FORCE_COLOR: "1". Every run: uses set -euo pipefail (bash), and every ${{ }} value from an event, an input or a secret goes through a step's env: rather than being interpolated into run:, as zizmor's template-injection rule requires. A job-level if: reads only inputs, github and needs, never secrets (the context isn't available there); a condition on a secret is tested inside the script, e.g. [ -n "$REGISTRY_TOKEN" ] || { echo "::notice::…"; exit 0; }.

• Shell conditionals under set -e are written as if …; then …; fi, never [ … ] && … as a last line, whose false test would fail the step.

• Working directory. app-root (default .) is applied per job as defaults.run.working-directory: ${{ inputs.app-root }}; workflow-level defaults can't read inputs. uses: steps ignore it, so every path input of an action is prefixed explicitly: node-version-file: ${{ inputs.app-root }}/package.json, actions/cache path: and key: hash globs, setup-uv cache-dependency-glob, and upload-artifact paths.

• Install frappe-nix-tools. lint, typecheck, marketplace and pr-policy all use the same step. Resolving the configuration afterwards fetches an org profile with pin-path standards-profile, so these jobs need no extra checkout:

- name: Install frappe-nix-tools at the frappe-nix revision flake.lock pins
  env:
    OVERRIDE: ${{ inputs.frappe-nix-override }}
  run: |
    set -euo pipefail
    node="$(jq -c '.nodes[.nodes.root.inputs["frappe-nix"]].locked' flake.lock)"
    rev="$(jq -r .rev <<<"$node")"; src="$(jq -r '"\(.owner)/\(.repo)"' <<<"$node")"   # Avunu/frappe-nix or a fork
    if [ -n "$OVERRIDE" ]; then
      uv tool install --python 3.14 "$GITHUB_WORKSPACE/$OVERRIDE/py/frappe_nix_tools"
      echo "FRAPPE_NIX_ALLOW_SKEW=1" >> "$GITHUB_ENV"      # self-test only (§3.7)
      echo "FRAPPE_NIX_EXPECT_REV=" >> "$GITHUB_ENV"
    else
      uv tool install --python 3.14 "frappe-nix-tools @ git+https://github.com/${src}@${rev}#subdirectory=py/frappe_nix_tools"
      echo "FRAPPE_NIX_EXPECT_REV=$rev" >> "$GITHUB_ENV"
    fi

lint passes --expect-rev "$FRAPPE_NIX_EXPECT_REV" only when the variable is non-empty. The package is self-contained (S10), so this install has every template and data file.

• Nix setup. The test, relock-plan and nightly Nix jobs all use the same steps, in this order:

  1. Free disk: sudo rm -rf /usr/share/dotnet /usr/local/lib/android /opt/ghc /opt/hostedtoolcache/CodeQL.

  2. nix-installer.

  3. Cache selection (S15). Let trusted be github.ref == format('refs/heads/{0}', inputs.integration-branch) && (github.event_name == 'push' || github.event_name == 'schedule'). A step maps TOKEN in its env: to ${{ (trusted) && secrets.NIX_CACHE_TOKEN || secrets.NIX_CACHE_READ_TOKEN }}; nothing else ever sees the write token.

     • inputs.nix-cache == '' → no cache action. (magic-nix-cache is throttled in every bench-sized job and evicts the node_modules caches; frappe-nix's own self-tests may still use it for their small closures.)

     • cachix:<name> → cachix/cachix-action with name: <name>, authToken from that step's mapped token, and skipPush: ${{ !(trusted) }}.

     • attic:<endpoint>/<cache> → nix profile install --inputs-from . nixpkgs#attic-client (pinned by the app's flake.lock), then always attic login ci <endpoint> ${TOKEN:+"$TOKEN"} (a public cache needs no token but still needs the server configured), then attic use ci:<cache>. A final step if: success() && <trusted> runs attic push ci:<cache> ./result .dev-dist/devshell-profile with the write token.

  4. Every nix develop uses --profile .dev-dist/devshell-profile, so the dev-shell closure can be pushed.

  Org setup: FRAPPE_NIX_CACHE is an org variable; FRAPPE_NIX_CACHE_TOKEN (write) is an org Actions secret only; FRAPPE_NIX_CACHE_READ_TOKEN (pull-only, or unset for a public cache) is an org Actions secret and an org Dependabot secret. That is the whole drop-in. Dependabot runs, which execute bumped third-party code, never hold a credential that can write the cache.

• Self-test only. The input frappe-nix-override (a path relative to the workspace) adds --override-input frappe-nix "path:$GITHUB_WORKSPACE/<override>" to every nix call, installs frappe-nix-tools from that path, and allows skew (§3.7).

4.2 The gate workflows: app-lint.yml, app-typecheck.yml, app-test.yml, app-marketplace.yml

1.1's single app-ci.yml is split so that a caller includes only the gates the app enables (S39). Each file holds exactly one job, named as its gate, and takes the subset of these inputs it uses:

on:
  workflow_call:
    inputs:
      app:                  { type: string, required: true }
      app-root:             { type: string, default: "." }
      integration-branch:   { type: string, default: "develop" }   # branches.integration (S41)
      nix-cache:            { type: string, default: "" }      # app-test.yml: "", "cachix:<name>", "attic:<endpoint>/<cache>"
      test-timeout-minutes: { type: number, default: 75 }      # app-test.yml
      frappe-nix-override:  { type: string, default: "" }      # frappe-nix self-test only
    secrets:
      NIX_CACHE_TOKEN:      { required: false }                # app-test.yml; write; used only on trusted runs (S15)
      NIX_CACHE_READ_TOKEN: { required: false }                # app-test.yml
      FETCH_TOKEN:          { required: false }                # every gate; private profile, frappe or siblings (§4)
    outputs:
      coverage: { value: "${{ jobs.test.outputs.coverage }}" }  # app-test.yml only, e.g. "63.2"
permissions: {}

Every gate job carries if: ${{ !startsWith(github.ref, 'refs/heads/version-') }} (a no-op under main+tags). The 1.1 input run-test is gone: frappe-nix's self-test simply doesn't call app-test.yml on PRs (§7 N4).

Context names (S3, S39). In the rendered ci.yml the caller job ids are lint, typecheck, test and marketplace, and every one has name: ci, so the check runs are ci / lint, … as in 1.1. N4's selftest-ci asserts these exact check-run names on its first run. If GitHub were to report the caller job id instead of its name, the fallback is a single reusable app-ci.yml with one boolean input per gate and job-level if: inputs.<gate>, called from one caller job ci; a disabled gate then shows as a skipped job, which is acceptable only because §4.8 never lists a disabled gate. N4 records which form shipped in docs/app-standards/ci.md.

• Dispatch mode is when github.event_name == 'workflow_dispatch'. In that mode, the first step of every gate job looks up the open PR whose headRefName == github.ref_name. If one exists, it asserts headRefOid == github.sha and fails with ::error::stale dispatch otherwise. Every gate job therefore has pull-requests: read (with explicit permissions, an unlisted scope is none, and the lookup would fail with "Resource not accessible by integration").

• Ratchet base (BASE, S24).

  • pull_request: git merge-base "$BASE_SHA" HEAD, with BASE_SHA = github.event.pull_request.base.sha passed through env:.

  • dispatch: git merge-base "origin/$INTEGRATION" HEAD.

  • push to the integration branch, and schedule: the ratchet is skipped.

Steps marked [module] run only when that module is on. Steps that need package.json or tools/ run only when those files are live. In lint, typecheck and marketplace, the steps from "install frappe-nix-tools" onwards (excluding uploads) are what frappe-nix gate <job> runs, with the ratchet base passed as --base "$BASE" and dispatch mode detected from GITHUB_EVENT_NAME; the workflow itself runs only the setup steps before it, the single frappe-nix gate <job> --format github step, and the upload.

There is no version-guard job. version-* only ever moves through the release workflow's REST PATCH, which raises no push event, so a push-triggered guard would never run. The fast-forward job asserts the D8 invariant itself right after the PATCH (§4.4), and audit row A2 checks it nightly. Under main+tags there is no release branch and nothing to guard.

The semgrep step in lint (module semgrep; semgrep.frappe-rules and semgrep.test-correctness switch the first two scans), with RULES set to the frappe-semgrep-rules store path read from the app's flake.lock (frappe-nix pin-path frappe-semgrep-rules fetches and verifies that tree, then prints its path):

RULES="$(frappe-nix pin-path frappe-semgrep-rules)"
uv run --frozen --project tools semgrep scan --error --metrics=off --config "$RULES/rules" <app>
uv run --frozen --project tools semgrep scan --error --metrics=off --include='**/test_*.py' \
  --config "$(frappe-nix data-path semgrep/test-correctness.yml)" <app>
if [ -d semgrep ]; then
  uv run --frozen --project tools semgrep scan --error --metrics=off --config semgrep <app>
fi

r/python.lang.correctness, which carbon_frappe uses, is dropped because it is unpinned.

4.3 app-pr-policy.yml: the job behind ci / pr-policy

Module commits (with ci). The major rule applies only under releases.version-scheme = "frappe-major", and frappe-nix policy reads that from the resolved configuration.

on:
  workflow_call:
    inputs:
      app:                 { type: string, required: true }
      integration-branch:  { type: string, default: "develop" }
      frappe-nix-override: { type: string, default: "" }
permissions: {}
jobs:
  pr-policy:
    name: pr-policy
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions: { contents: read, pull-requests: read }

Steps:

1. checkout with fetch-depth: 0;

2. setup-uv, then uv sync --frozen --project tools;

3. install frappe-nix-tools;

4. frappe-nix policy --pr, with env GH_TOKEN: ${{ github.token }}, INTEGRATION (inputs.integration-branch), EVENT_NAME, BASE_REF (github.event.pull_request.base.ref), HEAD_SHA (github.event.pull_request.head.sha || github.sha), PR_TITLE and REF_NAME. On a dispatch, BASE_REF and PR_TITLE are empty; frappe-nix policy then takes them from the PR it looks up (§5.9).

What frappe-nix policy --pr checks is in §5.9.

4.4 app-release.yml: releases without an App

Module releases (with ci). Profile values: releases.branching, listing.publish, listing.registry-fork, pilot-assets.enable, all rendered into the caller's with: (§4.7).

on:
  workflow_call:
    inputs:
      app:                { type: string, required: true }
      integration-branch: { type: string, default: "develop" }   # branches.integration
      release-branch:     { type: string, default: "" }          # branches.release: "version-16", or "" under main+tags
      publish:            { type: boolean, default: false }      # caller: listing.publish && vars.MARKETPLACE_PUBLISH == 'true'
      pilot-assets:       { type: boolean, default: false }
      registry-fork:      { type: string, default: "" }          # listing.registry-fork; required when publish is true
    secrets:
      REGISTRY_TOKEN: { required: false }
    outputs:
      released: { value: "${{ jobs.release-please.outputs.releases_created }}" }
      tag:      { value: "${{ jobs.release-please.outputs.tag_name }}" }
permissions: {}