Publish the permission allowlist entry for each named toolkit

[sameera]

The install documentation and the upgrade notes carry the exact account-scoped allowlist entry for each of the two named toolkits, and the install step prints the same text without writing any settings file.

Meta

• feature: docs/features/component-distribution
• estimate: S
• candidate stories: The install documentation carries both allowlist entries in the prefix form; The upgrade notes carry the same two entries; The install step prints the same text and writes nothing
• source: discovery of "installing Nexus components outside the target repo" (2026-08-16)

Decisions this goal hangs on

Does Nexus own the permission allowlist entry that lets its toolkit run, and if so which stage writes it?

• Decided: Nexus does not own the entry. Nexus documents it, and the user adds it. No stage writes it, because no stage may write a user-owned settings file. A durable product boundary is stated and it is wider than this question: Nexus writes the components it owns and never the files that govern what those components are permitted to do. The documented entry is account-scoped, in the user-level settings file at the Claude configuration directory, and that is the only way to obtain a grant matching the install's scope. There is one entry per named toolkit, so the documented content is two entries, in the trailing wildcard prefix form, which covers every verb and every argument list with one entry. The install step prints the exact text and writes nothing. Old entries are left alone, and the migration verb does not touch settings, because a settings file is neither namespaced nor Nexus-owned. The upgrade-day breakage this question was written to manage does not exist, because there are no accumulated entries naming the old invocation strings on this machine.
• Why: The decision turns on a scope mismatch. An interactive approval always saves to the repository's local settings file at the git repository root, and the user is given no scope choice, so relying on the prompt produces a repository-scoped grant repeated once per repository while the toolkit installs once per account. The documented account-scoped entry is therefore not the cheap substitute for the prompt. It is the only path that yields a grant matching the scope of the install. The published promise settles the rest: nexus deploy already prints that user-owned settings files are never touched, so a tool that prints that sentence and then writes a permission entry has broken a guarantee its own output makes, and the entry it writes is precisely the kind that decides what that tool is allowed to run. Two uncertainties are recorded rather than resolved, because neither changes the decision: the prefix boundary the permission dialog chooses is undocumented, and whether a bare executable name and a pathed invocation match the same rule is undocumented. Both affect only how often a user who ignores the documented entry is prompted.
• Refuted alternative: Have the setup stage offer to write the entry with consent at the moment it writes. It is the strongest alternative and it lost on its own logic. Its purpose is to remove the first-run interruption, and it does not remove it, because it replaces a prompt from Claude Code with a prompt from Nexus. What it buys over documenting is that Nexus authors the text so the entry is correctly shaped, and that benefit is obtainable without any write by printing the same text. Writing the entry silently at install is the same option without the consent gate: it needs the identical settings-file mechanism, so it is not cheaper, and it lands the write at the moment the user is least able to observe it. Writing nothing and documenting nothing is refuted by the scope finding, because it produces a repository-scoped grant once per repository and leaves a first-time adopter facing an unexplained prompt with no text to reach for.

Must both installation modes coexist, and what happens to repos that already carry a committed .claude directory?

• Decided: Exactly one Nexus component set exists per user account, at the Claude configuration directory resolved from $CLAUDE_CONFIG_DIR with ~/.claude as the default. The scope is the user account and not the machine, because that is what the configuration directory is.
• Why: The install is per user account, so a grant for the toolkit is a property of that one install rather than of any repository. A project-scoped entry would have to be written once per repository and again for every new repository that adopts Nexus, which contradicts the once-per-account model. A checked-in project settings file is additionally shared with the adopter's team, which is a different blast radius from a personal grant.
• Refuted alternative: Leave the committed component files in place and rely on the user-scope precedence that was measured. It loses because the precedence is an emergent implementation detail with no contract.

Do the skill scripts stay as separate TypeScript files, or collapse into the one portable bundle?

• Decided: The TypeScript capabilities collapse onto one named executable, and the Python capabilities remain a second named toolkit, so Nexus requires both node and python3.
• Why: Two named toolkits is why the documented allowlist content is two entries rather than one.
• Refuted alternative: Rewriting the Python capabilities into TypeScript so that one toolkit remains is out of scope, because every Python import is standard library, so the rewrite would reduce the number of toolkits rather than enable the installation.

[sameera]

Decisions this goal hangs on

Does Nexus own the permission allowlist entry that lets its toolkit run, and if so which stage writes it?

• Decided: Nexus does not own the entry. Nexus documents it, and the user adds it. No stage writes it, because no stage may write a user-owned settings file. A durable product boundary is stated and it is wider than this question: Nexus writes the components it owns and never the files that govern what those components are permitted to do. The documented entry is account-scoped, in the user-level settings file at the Claude configuration directory, and that is the only way to obtain a grant matching the install's scope. There is one entry per named toolkit, so the documented content is two entries, in the trailing wildcard prefix form, which covers every verb and every argument list with one entry. The install step prints the exact text and writes nothing. Old entries are left alone, and the migration verb does not touch settings, because a settings file is neither namespaced nor Nexus-owned. The upgrade-day breakage this question was written to manage does not exist, because there are no accumulated entries naming the old invocation strings on this machine.
• Why: The decision turns on a scope mismatch. An interactive approval always saves to the repository's local settings file at the git repository root, and the user is given no scope choice, so relying on the prompt produces a repository-scoped grant repeated once per repository while the toolkit installs once per account. The documented account-scoped entry is therefore not the cheap substitute for the prompt. It is the only path that yields a grant matching the scope of the install. The published promise settles the rest: nexus deploy already prints that user-owned settings files are never touched, so a tool that prints that sentence and then writes a permission entry has broken a guarantee its own output makes, and the entry it writes is precisely the kind that decides what that tool is allowed to run. Two uncertainties are recorded rather than resolved, because neither changes the decision: the prefix boundary the permission dialog chooses is undocumented, and whether a bare executable name and a pathed invocation match the same rule is undocumented. Both affect only how often a user who ignores the documented entry is prompted.
• Refuted alternative: Have the setup stage offer to write the entry with consent at the moment it writes. It is the strongest alternative and it lost on its own logic. Its purpose is to remove the first-run interruption, and it does not remove it, because it replaces a prompt from Claude Code with a prompt from Nexus. What it buys over documenting is that Nexus authors the text so the entry is correctly shaped, and that benefit is obtainable without any write by printing the same text. Writing the entry silently at install is the same option without the consent gate: it needs the identical settings-file mechanism, so it is not cheaper, and it lands the write at the moment the user is least able to observe it. Writing nothing and documenting nothing is refuted by the scope finding, because it produces a repository-scoped grant once per repository and leaves a first-time adopter facing an unexplained prompt with no text to reach for.

Must both installation modes coexist, and what happens to repos that already carry a committed .claude directory?

• Decided: Exactly one Nexus component set exists per user account, at the Claude configuration directory resolved from $CLAUDE_CONFIG_DIR with ~/.claude as the default. The scope is the user account and not the machine, because that is what the configuration directory is.
• Why: The install is per user account, so a grant for the toolkit is a property of that one install rather than of any repository. A project-scoped entry would have to be written once per repository and again for every new repository that adopts Nexus, which contradicts the once-per-account model. A checked-in project settings file is additionally shared with the adopter's team, which is a different blast radius from a personal grant.
• Refuted alternative: Leave the committed component files in place and rely on the user-scope precedence that was measured. It loses because the precedence is an emergent implementation detail with no contract.

Do the skill scripts stay as separate TypeScript files, or collapse into the one portable bundle?

• Decided: The TypeScript capabilities collapse onto one named executable, and the Python capabilities remain a second named toolkit, so Nexus requires both node and python3.
• Why: Two named toolkits is why the documented allowlist content is two entries rather than one.
• Refuted alternative: Rewriting the Python capabilities into TypeScript so that one toolkit remains is out of scope, because every Python import is standard library, so the rewrite would reduce the number of toolkits rather than enable the installation.