The plugin treats `.mdx` as the primary publish signal; the emitted CI template publishes `.md` only

[A-PachecoT]

Surfaced while building #11, which had to decide "will the repo's Action publish this file?" from local evidence.

The inconsistency

The plugin and the CLI disagree about what .mdx means.

The plugin treats .mdx as the PRIMARY intent-to-publish signal. hooks/lib.sh:is_doc():

*.mdx) return 0 ;;                                  # authoring it IS the intent to publish
*/docs/*.md|*/docs/*/*.md|…) return 0 ;;            # .md only under docs/

.mdx qualifies anywhere in the tree; .md only under a docs/ directory.

The CI template the CLI emits publishes .md only. From basalt onboard --print-workflow:

on:
  push:
    branches: [main]
    paths: ['**.md']
...
    run: git ls-files '*.md' | xargs basalt publish $FLAGS

Both the paths: filter and the git ls-files glob miss .mdx.

The consequence

A user who follows the plugin's own doctrine — author .mdx, install the emitted workflow — gets docs that the hook considers publishable and the Action never publishes. Nothing errors. The doc simply never appears.

This is not a tail case. It is the default path for a new user: basalt onboard writes that workflow, and .mdx is the extension the plugin signals hardest on.

Observed corroboration: a real repo-backed vault publishing .mdx today only does so because its workflow was hand-edited to add '**.mdx' to both filters. The emitted template would not have.

Why it is filed rather than fixed in #11

#11's hook evaluates the workflow's actual paths: list rather than assuming either extension, so it is correct under both shapes — under the emitted template an .mdx correctly keeps nagging (nothing publishes it), and under a widened one it correctly goes silent. That makes the hook honest about the inconsistency; it does not resolve it.

The decision this needs

One of the two is wrong, and it is a product call, not a hook call:

1. the emitted template should publish **.mdx as well — the plugin's is_doc() is right; or
2. .mdx should not be the plugin's primary publish signal — the template is right.

Whichever, the two should ship together, since the gap is only visible to a user who follows both.

[A-PachecoT]

Decision: the emitted template moves, the plugin does not — and is_doc() is not the mechanism

Taken with the measurement below. Recorded as ADR 0002 in this repo.

The premise in this issue does not hold: is_doc() is not the primary publish signal

This issue says hooks/lib.sh:is_doc() treats .mdx as the PRIMARY intent-to-publish signal. I
instrumented that rather than reading it off the source — firing post-edit.sh with the real captured
payload shape, each arm paired with the control that would falsify it (7/7):

Arm 1 — with a vault.yaml above the file. The dirty-list append is unconditional:

dirty list after editing four files:
    NOTES.mdx        ← the extension this issue names
    ROOT.md          ← .md NOT under docs/ — is_doc() REJECTS it, yet it is on the list
    docs/GUIDE.md
    CODE.ts          ← not prose at all, and still on the list
orphan list: EMPTY   ← control: is_doc()'s bucket did not fire

Arm 2 — no vault.yaml anywhere. Now is_doc() is the only thing deciding, and it does
discriminate: a root .md and a .ts raise nothing; the .mdx raises the orphan warning. The dirty
list stays empty (control: the two buckets are disjoint).

So is_doc() has exactly one caller — post-edit.sh, the elif branch — and it gates the orphan
warning, never the publish nag. Under a vault it does not run at all.

Consequence for the decision this issue asks for: option 2 is not available. Changing is_doc()
would not touch the reported symptom, because is_doc() is not on the code path that produces it.
The un-satisfiable nudge comes from published_by_repo_action(), which reads the workflow's actual
paths: list. This repo's own suite already pins both shapes, green today:

workflow paths:	doc	Stop hook
['**.md'] — the emitted template	.mdx	nags — correctly; the Action will not publish it
['**.md','**.mdx'] — hand-widened	.mdx	silent — correctly; the Action will publish it

The decision, and why

The emitted CI template is the one that is wrong.

1. The plugin is not the mechanism (measured above). Editing it is a cosmetic change to the wrong
   sensor while the symptom stays exactly as filed.
2. .mdx is first-class to the product the template automates. basalt pull writes canonical
   MDX, and cli/src/local-docs.ts:normalizeSlug strips /\.(md|mdx)$/i without distinguishing them.
   The template the CLI emits is narrower than the CLI emitting it — an internal contradiction inside
   the tooling, not a plugin-versus-CLI disagreement.
3. Narrowing is_doc() would be a regression. It would blind the orphan sensor to exactly the
   extension basalt pull writes — and that sensor exists for the one Basalt failure that does not
   announce itself (no vault.yaml → the publish lands in the wrong space at exit 0).

The concrete fix, and where it lives

Measured on the installed basalt-cli@0.10.0 — the template has three .md-only filters, not the
two this issue quotes:

cli/src/commands/onboard.ts:173    push        paths: ['**.md']
cli/src/commands/onboard.ts:175    pull_request paths: ['**.md']
cli/src/commands/onboard.ts:191    run          git ls-files '*.md' | xargs basalt publish $FLAGS

All three must widen. Widening only the two paths: filters swaps a silent no-publish for a silent
no-op: the workflow would trigger on a file it then never passes to basalt publish.

That file is in the private cofoundy/basalt repo (ADR 0001), so it ships from there, not here.

Plugin-side outcome: no code change, and that is the finding

The hook is already correct under both workflow shapes and already tested under both. When the
template widens, this repo's canonical fixture (WF_CANON in hooks/tests/run.sh) should widen with
it and the .mdx discriminating cell flips from nags to silent legitimately — keeping its paired
negative arm, since a doc that is edited and not pushed must still nag.

Leaving this open until the template half ships, since the issue is only closed when both halves agree.