@ethlete/agent-rules 0.1.0-next.3 → 0.1.0-next.31

package/README.md

@@ -15,6 +15,17 @@ npx ethlete-agents init   # writes ethlete-agents.config.json
 npx ethlete-agents sync   # writes the generated rules and skills
 ```
 
+With Yarn 4.18+ and `npmMinimalAgeGate`, a freshly published release is blocked until it ages. Add
+`npmPreapprovedPackages: ["@ethlete/*"]` to `.yarnrc.yml` to install new `@ethlete/*` versions right away.
+
+`init` pre-fills `vars` with the lint, format and Storybook commands for your repo, using its package manager; check them before
+the first sync. `sync`, `check`, `init` and `migrate` reject a flag they do not know and print the usage
+instead of running, and a config file that does not parse is reported by name.
+
+Adopting the rules in an existing app includes a styling audit: count the global CSS files,
+classes and hardcoded colours that break the `app-styling` rule, tell the user the numbers, and
+record the conversion as owed work.
+
 Commit the generated files, and add a drift check to CI:
 
 ```bash
@@ -38,6 +49,11 @@ Marker-block files (`AGENTS.md`, `.github/copilot-instructions.md`) are only rew
 between `<!-- ethlete:agent-rules:start -->` and `:end` - everything you wrote around
 them survives.
 
+When the repo has `@ethlete/cli` installed, `sync` also registers its design MCP server
+(`et design mcp` through the `packageRunner`, for example `yarn et design mcp`) as `ethlete-design`: in `.mcp.json` for Claude Code and in
+`.codex/config.toml` for Codex. Only that entry is written; other servers and tables
+stay as they are.
+
 ## Migrating a repo to the AGENTS.md layout
 
 `AGENTS.md` is the cross-tool standard, and Claude Code officially supports reading it
@@ -99,12 +115,26 @@ Prettier rewrites them and `check` then reports drift on every run:
   `.agents/skills/` is the cross-tool baseline) and adds `claude`, `cursor` or `copilot`
   when their directory exists; or list an explicit subset.
 - **`profile`** - `"consumer"` (default) emits `scope: consumer` and `scope: both`
-  content. `"sdk"` emits only `both`; the SDK repo uses it so its own hand-written,
-  authoring-side guides are not overwritten by the consumer-side versions.
+  content. `"sdk"` emits `scope: sdk` and `scope: both`; the SDK repo uses it so its own
+  hand-written, authoring-side guides are not overwritten by the consumer-side versions.
 - **`vars`** - values for the template tokens a guide declares. Defaults live in
   `content/defaults.json`; a guide whose variable has no default and no value is
-  skipped with a warning rather than emitted with a dangling placeholder.
-- **`exclude`** - content names to skip entirely.
+  skipped with a warning rather than emitted with a dangling placeholder. Some are
+  derived from the repo instead of defaulted - the `gitFlow*` ones from the `gitFlow`
+  block, `packageRunner` (`yarn`, `pnpm exec`, `bunx` or `npx`) from the root
+  `package.json`'s `packageManager` or the lockfile, and `commitRuleSource` / `commitValidation` from whether a commitlint config
+  exists (`commitlint.config.*`, `.commitlintrc*`, or a `commitlint` key in
+  `package.json`). Without one, the git-commit guide presents the format as the repo's
+  convention and never mentions a `commitlint` run - an agent that goes looking for a
+  promised validator and finds nothing reports the discrepancy instead of just
+  committing. `lintCommand` / `lintFixCommand` run the repo's `lint` script, else
+  `nx lint <project>` when Nx is installed, and `storybookStartCommand` runs its `storybook`
+  script; `sync` warns when a lint var names a script `package.json` does not have. Setting
+  any derived var in `vars` overrides the detection.
+- **`exclude`** - rule or skill names to skip entirely for every configured agent and
+  developer. For example, `"exclude": ["git-flow", "handoff"]` prevents those skills
+  from being generated; the next `sync` also removes copies generated previously. Unknown
+  names produce a warning so a typo cannot silently leave a skill enabled.
 - **`claudeMdImportsAgentsMd`** - set (usually by `migrate`) when `CLAUDE.md` is an
   `@AGENTS.md` import or symlink; the claude target then skips `.claude/rules/ethlete/`
   so the rules don't load twice. `sync` warns when the flag is set but the import is
@@ -113,56 +143,346 @@ Prettier rewrites them and `check` then reports drift on every run:
 Content that declares `requires` is only emitted when those packages are installed, so
 a repo without `@ethlete/query` never sees the query guide.
 
+## Git flow
+
+The branch convention lives in the same config, as one machine-readable grammar that the
+CLI, a git hook, a CI job and `@ethlete/timetrack` all read:
+
+```json
+{
+  "gitFlow": {
+    "keyPrefixes": ["FIP"],
+    "baseBranches": { "development": "next", "production": "main" }
+  }
+}
+```
+
+```bash
+npx ethlete-agents git-flow start FIP-2177          # name it and branch off the right base
+npx ethlete-agents git-flow check                   # the current branch
+npx ethlete-agents git-flow check "$SOURCE" --target "$TARGET"
+npx ethlete-agents git-flow check --all             # adoption report
+npx ethlete-agents git-flow repair dev-game-codes --key FIP-2900
+npx ethlete-agents git-flow explain feat/FIP-2177-user-management
+```
+
+The shapes:
+
+| Shape                                      | Branch from             | Merges into                    |
+| ------------------------------------------ | ----------------------- | ------------------------------ |
+| `feat/<KEY>-<subject>`                     | development             | development                    |
+| `sub/feat/<KEY>-<subject>/<KEY>-<subject>` | the main feature branch | the main feature branch        |
+| `release/<YYYY.MM.DD>`                     | development             | development **and** production |
+| `sub/release/<YYYY.MM.DD>/<KEY>-<subject>` | the release branch      | the release branch             |
+| `hotfix/<KEY>-<subject>`                   | production              | production                     |
+
+**Why nested branches carry a `sub/` prefix.** Git refuses a ref that is both a branch and
+a directory of branches, so `feat/FIP-2177-user-management/FIP-2178-reset` cannot exist
+while `feat/FIP-2177-user-management` does - the push is rejected with `refname conflict`.
+The prefix moves the nested tree out of the way while keeping the parent's full path inside
+the child's name, so the merge request target is still derivable from the name alone. The
+unprefixed spelling still parses, reports why it cannot exist, and `repair` moves it.
+Configurable as `subPrefix`.
+
+- **`enforcement`** - `"advisory"` (default) reports everything and blocks nothing, so a
+  repo can adopt the convention before it gates on it. `"gated"` applies each rule's
+  `severity`. A direct push to a base branch is blocked in both modes, and
+  `wrong-mr-target` can be raised to `"error"` on its own without ending the naming
+  grace period.
+- **`keyPrefixes`** - the project's issue prefixes. Leave it empty and anything shaped
+  like `keyPattern` counts, which reads `chore/angular-22` as issue `ANGULAR-22`.
+- **`severity`** - per rule: `unknown-type`, `missing-key`, `key-case`,
+  `missing-subject`, `type-alias`, `deprecated-prefix`, `release-date`,
+  `wrong-mr-target`, `protected-push`.
+- **`deprecatedShapes`** - legacy spellings that still classify correctly and only earn a
+  rename suggestion. `dev-*` ships as the old spelling of a main feature branch.
+
+The grammar is also importable on its own - `@ethlete/agent-rules/git-flow` has no
+dependencies and touches no Node built-ins, so it runs in a browser:
+
+```ts
+import { parseBranch, planStart, resolveGitFlowConfig } from '@ethlete/agent-rules/git-flow';
+
+const { storyKey, taskKey, findings } = parseBranch({ branch, config: resolveGitFlowConfig() });
+```
+
+### `start` - the prospective flow
+
+`git-flow start <KEY>` reads the issue from Jira, computes the name from the grammar and
+creates the branch off the correct base. It prints the plan first and asks before writing;
+`--dry-run` stops after the plan and `--yes` skips the question. It refuses on a dirty
+working tree, when the branch already exists, and when the base branch is nowhere to be
+found.
+
+A Task with a parent Story nests under that Story's feature branch, which therefore has to
+exist already - `start` says so rather than inventing a parent. `--of <branch>` picks the
+parent explicitly, `--hotfix` branches off production, `--release <date>` makes a release
+branch, and `--subject <text>` skips Jira entirely.
+
+The issue is read through the Timetrack app - see [Jira, through Timetrack](#jira-through-timetrack).
+No repository holds a Jira credential, so the only thing the committed config still says about
+Jira is how an issue type becomes a branch type:
+
+```json
+{
+  "jira": {
+    "typeByIssueType": { "Bug": "fix" }
+  }
+}
+```
+
+- **`typeByIssueType`** - the branch type per Jira issue type; anything unlisted becomes
+  `feat`. `--type` overrides it per call.
+
+The branch subject comes from the instance's own subject field, which Timetrack resolves
+because the field id is a property of the instance rather than of this repo. An issue that
+sets no subject falls back to its summary, and the printed plan says which of the two it used.
+
+### `repair` - renaming a branch that does not conform
+
+`git-flow repair [ref]` derives the conforming name (`--key FIP-2900` when the old name
+carries no issue key, `--to <branch>` to override), renames the branch locally and on the
+remote, and retargets the open merge requests aimed at it through the GitLab API.
+`GITLAB_TOKEN` needs the `api` scope, and is sent only to the hosts named in `GITLAB_HOST`
+(comma-separated) or, in a GitLab CI job, `CI_SERVER_HOST`.
+
+Everything is checked before the first mutation, and it refuses rather than half-finishing:
+
+- An open merge request whose **source** is the branch blocks the repair. GitLab cannot
+  move a merge request to another source branch, and closing it would lose its discussion -
+  merge or close it first.
+- A branch that is pushed but whose merge requests cannot be listed (no token, or a remote
+  that is not a configured GitLab host) blocks too. `--no-mr-check` asserts that none point at it.
+- If a retarget fails halfway, the old branch is still there and the recovery commands are
+  printed.
+
+## Jira, through Timetrack
+
+A Jira token in every repository is a secret nobody can rotate. There is one on this machine
+instead, in the Timetrack app's keychain entry, and every repository asks the running app:
+
+```bash
+npx ethlete-agents timetrack status                # is it reachable, and what does it hold?
+npx ethlete-agents timetrack issue FIP-2177        # summary, type, parent, branch subject
+npx ethlete-agents timetrack search "password"     # open issues of the picked projects
+npx ethlete-agents timetrack project               # which project does this repo log into?
+npx ethlete-agents timetrack create --summary "…"  # file a ticket with the instance's settings
+npx ethlete-agents timetrack log --issue FIP-2177 --minutes 45
+npx ethlete-agents timetrack approval <id>         # where a queued write stands
+```
+
+`timetrack snapshot [from] [to] [--out <file>]` records the rows of real days (default: the last 7) with
+the git HEAD and uncommitted files of the current repo; without `--out` the file lands in the app's data
+directory under `snapshots/`, never in a repo. `timetrack snapshot --compare <file>` reads the same days
+again and prints every row gone, new or changed (`--json` for a script); it exits 1 when anything changed.
+
+`--json` prints the raw answer instead of lines. `git-flow start` uses the same channel.
+
+**Every write waits for the user.** `create`, `log` and every other write answer at once with an
+approval id and write nothing; the user approves or rejects the request in the app, and
+`approval <id>` reads the outcome. A request still waiting at the end of its day expires.
+`TIMETRACK_CLIENT` names the caller in the queue.
+
+**How it connects.** The app binds a loopback socket and writes its port and a fresh token
+into `agent.json` in its own data directory (`~/.local/share/io.ethlete.timetrack/` on Linux,
+`~/Library/Application Support/…` on macOS, `%APPDATA%\…` on Windows), readable by its owner
+alone. The token lives no longer than the run, so a caller left over from an earlier one is
+refused rather than trusted, and a request carrying an `Origin` header is refused outright -
+a page the user happens to have open must not reach Jira through a port it guessed.
+`TIMETRACK_AGENT_DISCOVERY` names the file for a machine that keeps it elsewhere.
+
+**What the app answers, not this package.** The instance, the credentials, the picked
+projects, the subject field and the ticket shape are all settings there. That is what makes
+`create` file a ticket indistinguishable from one the app filed, and it is why none of them
+appear in a repo's config any more.
+
+**`log` writes to the day, not to Tempo.** It adds the same row the app's own timeline draws
+for work nothing observed, and the user reviews the day before syncing it. A worklog posted
+behind the review would double-book against whatever the evidence already proposed for that
+hour.
+
+**When the app is not running** every command says so and exits non-zero. There is no
+fallback to an environment variable on purpose - a fallback is how the per-repo secret comes
+back.
+
 ## Hooks (opt-in)
 
-Claude Code hooks run commands on the developer's machine, so none are emitted by
-default - opt in per hook in the config:
+Hooks run commands on the developer's machine, so none are emitted by default - opt in
+per hook in the config:
 
 ```json
 {
-  "hooks": ["context-warning"]
+  "hooks": ["context-warning", "subagent-model-policy"]
 }
 ```
 
-`sync` writes the script to `.claude/hooks/ethlete/` and registers it in
-`.claude/settings.json` (your own entries are left untouched); removing the name from
-`hooks` unregisters and deletes it again.
+They are emitted for whichever of the `claude` and `codex` targets is enabled:
+
+| Target   | Script                   | Registered in           |
+| -------- | ------------------------ | ----------------------- |
+| `claude` | `.claude/hooks/ethlete/` | `.claude/settings.json` |
+| `codex`  | `.codex/hooks/ethlete/`  | `.codex/hooks.json`     |
+
+Your own entries in those files are left untouched; removing the name from `hooks`
+unregisters and deletes the script again. Codex only loads project-local hooks once the
+`.codex/` layer is trusted, and honours `[features] hooks = false`.
 
 Available hooks:
 
-- **`context-warning`** - warns once per tier (and instructs Claude) when the session
-  context crosses 70% / 85% of the token budget, recommending `/handoff`. The budget is
-  capped at the 200k long-context pricing boundary: on 1M-window models every request
-  past 200k input tokens bills the whole context at a premium rate, so the warnings
-  fire at ~140k/~170k instead of deep into the expensive range.
+- **`context-warning`** - warns once per tier (and instructs the agent) when the session
+  context crosses 70% / 85% / 95% of the token budget, recommending a handoff. Under Claude the
+  budget is capped at the 200k long-context pricing boundary: on 1M-window models every
+  request past 200k input tokens bills the whole context at a premium rate, so the
+  warnings fire at ~140k/~170k instead of deep into the expensive range. Codex uses
+  the model-specific 272k pricing boundary for GPT-5.6, GPT-5.5 and GPT-5.4, and the
+  rollout's reported context window for models without that pricing rule.
+
+  The 85% tier asks the agent to choose - finish the task, or hand off - because a session
+  is often a step or two from done when it fires. The 95% tier takes that choice away. Every
+  prompt after the first warning carries a short reminder instead of a new warning: the
+  remaining budget, and how to work so that either ending stays cheap. The `handoff` skill
+  calls this handoff mode.
+
+  Under Claude the hook runs on four events, because a warning that only a user prompt can
+  trigger never reaches a long autonomous run. `SessionStart` names the budget before the
+  first request. `UserPromptSubmit` carries the tiered warning and the reminder.
+  `PostToolBatch` fires between the agent's own model requests, so it learns the count while
+  it works. `Stop` fires as a turn ends over 85% and the turn then continues, so the agent
+  must take one of three and say which: finish, hand off, or cross the boundary on purpose
+  for a reason it states. Each event speaks once per tier. Codex has none of the three, so
+  its registration stays on `UserPromptSubmit`.
+
+  Two things are Claude-only: the separate user-facing line (Codex documents only
+  `additionalContext`, so there the warning is folded into the text the model is told to
+  relay), and the auto-mode escalation that writes the handoff file unprompted - Codex's
+  `permission_mode` values are undocumented, so no value enables it.
+
+  Codex sub-agents are tracked by their own thread ids even though they share the root
+  session id. A sub-agent warning tells that child to report its state to the parent; it
+  never tells the user or the main agent to hand off the root session.
+
+- **`subagent-model-policy`** (Claude Code only) - gates every call to the subagent tool.
+  A call that names no `model` is denied and the model table is returned instead: haiku for
+  a lookup, opus for real work, sonnet in between, fable for judgment-heavy work. Without
+  it a subagent inherits the model leading the session, which is how an expensive model
+  ends up doing every grep it delegates; with it, that mistake costs one tool call.
+
+  A call that names `fable` asks the user - it is the most expensive option, and only the
+  user knows whether the task is judgment-heavy. A fork and an agent type whose own
+  definition sets a model both pass untouched, because `model` would change nothing there.
 
 Hooks can be turned off per machine - see the local config below.
 
+## Git hooks (opt-in)
+
+Separate from the agent hooks above, and opt-in for the same reason - a generated block
+that can reject a push is a higher-stakes artifact than a markdown one:
+
+```json
+{
+  "gitHooks": ["pre-push", "post-checkout"]
+}
+```
+
+Each one is written as an `# ethlete:git-flow:start` … `end` block **appended** to your
+`.husky/<name>`, so an existing hook there (a git-lfs hook, typically) keeps working and
+keeps reading stdin first - which is why the block never reads stdin itself. Removing the
+name from `gitHooks` takes the block back out and leaves the rest of the file alone.
+
+- **`pre-push`** - runs `git-flow check --push` on the current branch. In `advisory` mode
+  only a direct push to a base branch can actually stop it.
+- **`post-checkout`** - reports a non-conforming name on a branch that is on no remote yet,
+  which is the whole window in which renaming it is free.
+
+Only `.husky/` is written, never `.git/hooks/`: the generated files are committed and CI's
+`check` diffs them, so a hook outside the working tree could never be in sync. Without a
+`.husky/` directory `sync` warns and writes nothing. The block calls
+`node_modules/.bin/ethlete-agents` directly rather than through `npx`, so a repo where the
+package is missing gets silence instead of a registry lookup that would fail the push.
+`ETHLETE_GIT_FLOW_SKIP=1` silences both hooks on one machine.
+
+## CI job
+
+On GitLab, the merge request target is the half no local hook can see. The job needs no
+configuration beyond the predefined variables:
+
+```yaml
+Git Flow:
+  stage: Checks
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  allow_failure: true
+  script:
+    - >
+      npx ethlete-agents git-flow check "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"
+      --target "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
+```
+
+`allow_failure: true` on top of `advisory` mode is deliberate belt and braces: the job
+reports for a whole grace period before it can ever be the reason a merge request is red.
+
+## Output styles (Claude Code)
+
+An output style replaces Claude Code's own answer style for a whole session. This package
+ships one - **`ste-clarity`**, which writes every answer in ASD-STE100 Simplified Technical
+English - and installs it into the machine's Claude config rather than into a repo, because
+that is where Claude Code reads styles from:
+
+```bash
+npx ethlete-agents output-style             # install ste-clarity and switch to it
+npx ethlete-agents output-style --dry-run   # print what would change
+npx ethlete-agents output-style --remove    # take it back out
+```
+
+Two files, both under `~/.claude` (or `$CLAUDE_CONFIG_DIR`, or `--config-dir <path>`):
+
+| File                           | What changes                                                       |
+| ------------------------------ | ------------------------------------------------------------------ |
+| `output-styles/ste-clarity.md` | The style itself, written whole                                    |
+| `settings.json`                | `"outputStyle": "ste-clarity"` - every other setting is left alone |
+
+- **`--no-activate`** writes the style file but not the setting, so switching to it is then
+  `/output-style ste-clarity` inside a session.
+- A style file this command did not write is never overwritten or deleted - it says so and
+  stops, and `--force` is the way through. A copy of the same style that differs only in
+  layout still counts as its own.
+- Nothing here is repo-local, so `sync` and `check` neither write nor diff it. `--remove`
+  clears `outputStyle` only while it still points at that style.
+
+**Claude Code only.** Codex has no output-style mechanism - everything it is told comes
+from `AGENTS.md`, which `sync` already writes.
+
 ## Per-machine local config
 
-A gitignored `ethlete-agents.config.local.json` at the repo root holds the values that
-differ per developer, without touching any committed file:
+A gitignored `ethlete-agents.config.local.json` at the repo root holds the agent behaviour
+that differs per developer, without touching any committed file:
 
 ```json
 {
   "disableHooks": true,
-  "sdkSourcePath": "/absolute/path/to/ethlete-sdk"
+  "disableAutoHandoffSave": true
 }
 ```
 
 - **`disableHooks`** - `true` disables every generated hook; an array
   (`["context-warning"]`) just the named ones. The hook scripts read the file at
   runtime, so toggling takes effect on the next prompt - no `sync` needed.
-- **`sdkSourcePath`** - a local `ethlete-sdk` checkout. The `sdk-source` and
-  `sdk-local-build` skills read it when the agent needs the SDK's own sources, or has to
-  build the SDK and install it here through a `file:` dependency. A relative path is
-  resolved from the repo root.
+- **`disableAutoHandoffSave`** - keeps the `context-warning` hook's tiered warnings but
+  drops the auto-mode escalation: at the critical tier it recommends `/ethlete-handoff`
+  instead of saving the handoff file itself.
 
 Everything in this file is read at runtime, never by `sync`: the generated files stay
 identical on every machine and in CI, which is what lets `check` diff them. That is also
-why the file takes nothing beyond these keys - `sync`/`check` warn about unknown keys,
-and about an `sdkSourcePath` that is missing or is not an SDK checkout. Add the filename
-to your repo's `.gitignore`.
+why the file takes nothing beyond these keys - `sync`/`check` warn about unknown keys. Add
+the filename to your repo's `.gitignore`.
+
+### Where the sibling checkouts live
+
+`sdkSourcePath`, `apiRepoPaths` and `apiRepoBranches` used to live in the file above. They
+moved to `ethlete.config.local.json`, which [`@ethlete/cli`](../cli/README.md) owns, because
+`et api` needs the same values the skills do. `sync`/`check` still read that file and warn
+about a path that is missing or is not the checkout it claims to be, and they tell you to
+move any of the three keys still found in the agents file.
 
 ## Authoring content
 
@@ -178,11 +498,24 @@ scope: consumer # consumer | sdk | both
 requires: ['@ethlete/core'] # optional
 paths: ['**/*.css'] # optional; becomes Claude `paths` and Cursor `globs` on rules
 vars: [docsBaseUrl] # optional
+modelInvocation: false # optional; a skill only the user may start
 ---
 ```
 
+A content file vendored from another repository keeps its upstream wording apart from the
+link syntax, and names its source in the body. `THIRD-PARTY-LICENSES.md` lists each one,
+its upstream commit and its license.
+
+`content/output-styles/<name>.md` is a third kind, and the only one this package does not
+compile: it is a Claude Code output style verbatim, so its frontmatter is Claude's
+(`name`, `description`, `keep-coding-instructions`) and `output-style` installs the file
+as it is, apart from a marker line that records where it came from.
+
 In a body, `{% varName %}` substitutes a variable, `{% skill:other-name %}` links to
-another guide the way the current target expects, and `{% resource:file.mjs %}` links to
-a bundled file. The delimiter is `{% … %}`, not `{{ … }}`, so Angular templates in
-examples pass through untouched. Resource files get variable substitution too, but no
-links.
+another emitted package guide, and `{% resource:file.mjs %}` links to a bundled file.
+Skill links are required dependencies: after scope, package, variable, and exclusion
+filtering, `sync` and `check` fail with the source and missing target instead of emitting
+a dangling name. Optional guidance must be self-contained when its guide is absent. Use
+the structured marker instead of a plain `` `name` skill`` reference so validation can
+see it. The delimiter is `{% … %}`, not `{{ … }}`, so Angular templates in examples pass
+through untouched. Resource files get variable substitution too, but no links.

package/THIRD-PARTY-LICENSES.md

@@ -0,0 +1,35 @@
+# Third-party content
+
+Content in this package that comes from another repository, with the license it keeps.
+To update one, copy it again from upstream and record the new commit here.
+
+## [mattpocock/skills](https://github.com/mattpocock/skills)
+
+Commit `3cca18b` (2026-09-04). Vendored skills, kept as written upstream apart from the
+generator's own link syntax:
+
+- `content/skills/grill-with-docs` - the entry point; calls the other two.
+- `content/skills/grilling` - plus our own section "Local addition" after the upstream footer.
+- `content/skills/domain-modeling`
+
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/content/defaults.json

@@ -4,7 +4,7 @@
   "formatCommand": "npx prettier --write <files>",
   "storybookUrl": "http://localhost:6006",
   "storybookStartCommand": "npm run storybook",
-  "docsBaseUrl": "https://ethlete-sdk-docs.web.app",
+  "docsBaseUrl": "https://ethlete-sdk-docs-next.web.app",
   "sdkStorybookUrl": "https://ethlete-sdk.web.app",
   "handoffDir": ".agents/handoffs"
 }

package/content/git-hooks/post-checkout.sh

@@ -0,0 +1,10 @@
+if [ "$3" = "1" ] && [ -z "$ETHLETE_GIT_FLOW_SKIP" ] && [ -x node_modules/.bin/ethlete-agents ]; then
+  ethlete_branch=$(git rev-parse --abbrev-ref HEAD)
+
+  # Only while the branch is on no remote: that is the whole window in which renaming it is free.
+  if [ -z "$(git for-each-ref --format='%(refname)' "refs/remotes/*/$ethlete_branch")" ]; then
+    node_modules/.bin/ethlete-agents git-flow check || true
+  fi
+
+  unset ethlete_branch
+fi

package/content/git-hooks/pre-push.sh

@@ -0,0 +1,5 @@
+# Never `npx`: it reaches the registry when the package is absent, and a network error here would
+# reject the push. A missing binary must make this block do nothing at all.
+if [ -z "$ETHLETE_GIT_FLOW_SKIP" ] && [ -x node_modules/.bin/ethlete-agents ]; then
+  node_modules/.bin/ethlete-agents git-flow check --push || exit 1
+fi