chore: remove npm-mirror leftovers and document the scoped package #2

Merged

jercik merged 3 commits from chore/remove-npm-mirror into main 2026-10-22 17:49:50 +00:00

Conversation 3 Commits 3 Files changed 8 +49 -818

jercik commented 2026-10-22 17:20:56 +00:00

Owner

• Copy link
• Copy Markdown

Removes the npm-mirror leftovers after align 9.0.0. The package now publishes only to the Forge registry as @j4k-oss/perplexity-agent-mcp, so the .npm-mirror marker, .github/workflows/release-npm.yml and the npm-mirror job in release.yml (663 to 208 lines) are gone. The Forge publish is untouched. The remaining files are what align regenerated: AGENTS.md, one workflow comment and two check-dts messages.

The README now points at the scoped Forge package and carries the registry flag on every npm command, because the j4k-oss scope on npmjs has an unconfirmed owner. It says the unscoped package is frozen and must be uninstalled globally first, since both ship the same command.

🤖 Generated with Claude Code

Removes the npm-mirror leftovers after align 9.0.0. The package now publishes only to the Forge registry as `@j4k-oss/perplexity-agent-mcp`, so the `.npm-mirror` marker, `.github/workflows/release-npm.yml` and the `npm-mirror` job in `release.yml` (663 to 208 lines) are gone. The Forge publish is untouched. The remaining files are what align regenerated: `AGENTS.md`, one workflow comment and two check-dts messages. The README now points at the scoped Forge package and carries the registry flag on every npm command, because the `j4k-oss` scope on npmjs has an unconfirmed owner. It says the unscoped package is frozen and must be uninstalled globally first, since both ship the same command. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jercik added 2 commits 2026-10-22 17:20:56 +00:00

chore: remove npm-mirror leftovers after align 9.0.0 ... e5697faf47

Drop the `.npm-mirror` marker, `.github/workflows/release-npm.yml` and the
`npm-mirror` job from `.forgejo/workflows/release.yml`, and sync the files
align 9.0.0 regenerates (workflow comment, check-dts guard messages,
AGENTS.md).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs: point install instructions at the scoped Forge package ... e6932044d6

The unscoped npmjs package is frozen. Document `@j4k-oss/perplexity-agent-mcp`
with the registry flag on every npm command, the `~/.npmrc` mapping, and the
global-install conflict with the unscoped package.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

forgejo-actions commented 2026-10-22 17:26:54 +00:00

• Copy link
• Copy Markdown

Review 01M5JB47ECFSH4WYG74CYNEJQP — head d503ab850acb475fbc3f1760601616baf13f65b3

Review — j4k-oss/perplexity-agent-mcp @ 041cee27c1

Scope: diff against base tree 202843f6ef87
Status: dispatched — coverage complete (4/4 slots terminal)
Facts: current review-wide projection

Computed under:

{
  "abandonment": "abandonment-v1",
  "anchor_recipe": 1,
  "batch_policy": "batch-v1",
  "coverage": "coverage-v3",
  "dispatch_policy": "dispatch-v2",
  "grounder_version": 1,
  "grounding_read_rule": "grounding-read-v1",
  "promotion_policy": "promotion-v1",
  "report": "report-v4",
  "tally": "tally-v1",
  "triage_settle": "triage-settle-v2"
}

Findings (3)

medium — The model-selection summary independently copies the tool configuration

• claim: 01M5JBC048B6JAF8VJZTBXWH6B
• anchor: README.md (snippet)

The server also selects task‑appropriate Perplexity models—`sonar-pro` for lookups (see `getLookupModel()` in `src/index.ts`) and `sonar-reasoning-pro` for deeper research (see `getAnswerModel()` in `src/index.ts`).

• lens: writing-quality · arm: default
• verdicts: 1 valid / 0 invalid / 0 uncertain
  • pass 01M5JBDQMSX222282AQPAJJJGA · valid: The exact-grounded sentence copies lookup -> sonar-pro and answer -> sonar-reasoning-pro. The reviewer identifies registerLookupTool in src/tools/lookup.ts and registerAnswerTool in src/tools/answer.ts as the authorities and lists the same mappings there, with no exclusive members. This satisfies the required comparison and establishes a medium maintenance defect: the prose independently repeats repository-selected models, rather than a vendor-defined set. The reported MCP interface gives callers no model-selection action requiring those names. The pointer exception does not exempt the members stated beside the pointers. The reported nonexistent helpers also make the current navigation misleading. Preserve the purpose that models are configured per tool and point to the actual registration functions; exact model names are unnecessary for that implementation-orientation task. The earlier adjudication supplies no concrete refutation, and the current evidence independently supports the conclusion.
• disposition: none

Changing the Perplexity model selected by a tool requires a second manual edit to this implementation overview. Readers looking for the configuration are also directed to getLookupModel() and getAnswerModel() in src/index.ts, neither of which exists.

The authority is the options passed to performChatCompletion in registerLookupTool in src/tools/lookup.ts and registerAnswerTool in src/tools/answer.ts. The source defines the mappings lookup → sonar-pro and answer → sonar-reasoning-pro. The prose covers exactly lookup → sonar-pro and answer → sonar-reasoning-pro; neither list has an exclusive member. These are selections made by this repository, rather than a description of the vendor's available models.

Replace this sentence with: “The model and search-context settings are defined in registerLookupTool in src/tools/lookup.ts and registerAnswerTool in src/tools/answer.ts.” This preserves the implementation reader's task of finding and changing the settings without maintaining another model inventory. It follows writing-for-agents' One Idea, One Place guidance; callers do not select these models through the MCP interface, so exact model names are not needed to invoke either tool.

I read README.md, src/index.ts, src/server.ts, and both tool registration modules and traced their calls to performChatCompletion. This is a static source comparison. A data flow deriving this README sentence from the tool definitions, or a caller-facing requirement for the fixed model identities, would refute the unnecessary-copy finding; neither is present in the examined call path.

medium — The documented Node minimum is lower than the package requirement

• claim: 01M5JBCE9G9G8KM21N9NMF6GZD
• anchor: README.md (snippet)

- Node.js v24.0.0 or newer

• lens: writing-quality · arm: default
• verdicts: 1 valid / 0 invalid / 0 uncertain
  • pass 01M5JBDQMSX222282AQPAJJJGA · valid: The exact-grounded README prerequisite allows Node.js 24.0.0 or newer. The reviewer quotes the contrasting package.json engines.node declaration as >=24.15.0. Versions from 24.0.0 through 24.14.x therefore satisfy the documentation but fall outside declared support. This is a concrete documentation mismatch; it does not depend on demonstrating a runtime crash, and installation rejection is explicitly conditional on engine enforcement. The setup reader needs the supported minimum to choose a runtime, so retaining the exact prerequisite serves a distinct task and is permitted by the task-critical-information exception. Align the README minimum with 24.15.0 or derive it from the manifest. Medium severity is appropriate. Reassessing the historical claim reveals no counterevidence or changed contract that defeats the current comparison.
• disposition: none

A user following Requirements can choose Node 24.0.0 even though this package declares that runtime unsupported. The README says “Node.js v24.0.0 or newer”, whereas package.json sets engines.node to “>=24.15.0”. Readers on Node 24.0 through 24.14 can therefore complete the documented prerequisite and still encounter an engine warning or rejection when installing with engine enforcement.

Change the requirement to “Node.js v24.15.0 or newer”. This is the smallest correction that preserves the setup reader's ability to choose a runtime before installation. The exact prerequisite belongs on this surface: a bare pointer to package.json would require an extra lookup to decide whether installation is supported. It follows the writing guides' requirements for verifiable claims and task-sufficient prerequisites.

I compared the README Requirements section with package.json's engines field. This establishes a documentation/manifest mismatch by static inspection; I did not test execution on older Node releases or claim a particular runtime crash. A change to the governing engine constraint or evidence that the README is intentionally documenting a different supported artifact would refute the mismatch; neither appears in the reviewed setup instructions.

low — The prompt references send readers to a file that does not define them

• claim: 01M5JBD1PQTNF40N2JE7YJEG5Q
• anchor: README.md (snippet)

The lookup tool uses a compact fact‑extraction prompt focused on code/docs facts (see `LOOKUP_SYSTEM_PROMPT` in `src/index.ts`). The answer tool uses a technical decision/analysis prompt tailored for migrations and architecture choices (see `ANSWER_SYSTEM_PROMPT` in `src/index.ts`).

• lens: writing-quality · arm: default
• verdicts: 1 valid / 0 invalid / 0 uncertain
  • pass 01M5JBDQMSX222282AQPAJJJGA · valid: The exact-grounded passage locates LOOKUP_SYSTEM_PROMPT and ANSWER_SYSTEM_PROMPT in src/index.ts. The reviewer supplies a concrete contradictory trace: src/prompts.ts defines both constants, the lookup and answer tool modules import them from ../prompts.js and pass them as the system option to performChatCompletion, and src/index.ts has neither definitions nor re-exports. That account explains why a contributor following either reference reaches the wrong file; it is more than a bare assertion of inspection. Nothing in the batch contradicts this trace, and the historical adjudication adds no applicable refutation. Changing both references to src/prompts.ts while retaining the tool-purpose explanations repairs the navigation without duplicating prompt contents. Low severity is appropriate.
• disposition: none

A contributor trying to inspect or tune either system prompt is sent to src/index.ts, which contains CLI startup rather than the prompt definitions. Both named constants are defined in src/prompts.ts.

The overview explicitly directs readers to LOOKUP_SYSTEM_PROMPT and ANSWER_SYSTEM_PROMPT “in src/index.ts”. In the actual call path, src/tools/lookup.ts and src/tools/answer.ts import those constants from ../prompts.js and pass them as the system option to performChatCompletion.

Change both source references to src/prompts.ts, retaining the explanations that lookup extracts documentation facts and answer supports technical decisions. That preserves the overview's reader task and the existing useful pointer structure without copying the prompts or their contents. This follows the writing guides' precise-language and One Idea, One Place guidance.

I read the README overview, src/index.ts, src/prompts.ts, and both tool modules. This is a static trace, not a runtime test. Definitions or re-exports of these constants in src/index.ts would refute the claim; that file has neither.

Other claims

• grounding-pending (0)
• ungrounded (0)
• rejected (0)
• duplicate-of (0)
• unadjudicated (0)

Coverage

Coverage pass: 01M5JB5JMSJDHNZ315JAARGZEJ
Accounting: complete
Slot health: healthy

lens	part	arm	unit status	runs	loss
restated-sets	whole	default	no-claims	1	no
general-bug	whole	default	no-claims	1	no
writing-quality	docs-and-workflows	default	claims-emitted	1	no
project-docs	whole	default	no-claims	1	no

• test-trimming — skipped-by-dispatch: no test files changed
• unix-cli — skipped-by-dispatch: changes are CI workflows, docs, and small script edits; no CLI interface changes evident
• use-effect — skipped-by-dispatch: no React code changed; only workflows, docs, and build scripts
• react — skipped-by-dispatch: no React components or manifests changed

<!-- review:summary --> **Review** `01M5JB47ECFSH4WYG74CYNEJQP` — head `d503ab850acb475fbc3f1760601616baf13f65b3` # Review — j4k-oss/perplexity-agent-mcp @ 041cee27c1a9 Scope: diff against base tree `202843f6ef87` Status: dispatched — coverage complete (4/4 slots terminal) Facts: current review-wide projection Computed under: ```json { "abandonment": "abandonment-v1", "anchor_recipe": 1, "batch_policy": "batch-v1", "coverage": "coverage-v3", "dispatch_policy": "dispatch-v2", "grounder_version": 1, "grounding_read_rule": "grounding-read-v1", "promotion_policy": "promotion-v1", "report": "report-v4", "tally": "tally-v1", "triage_settle": "triage-settle-v2" } ``` ## Findings (3) ### medium — The model-selection summary independently copies the tool configuration - claim: `01M5JBC048B6JAF8VJZTBXWH6B` - anchor: `README.md` (snippet) ``` The server also selects task‑appropriate Perplexity models—`sonar-pro` for lookups (see `getLookupModel()` in `src/index.ts`) and `sonar-reasoning-pro` for deeper research (see `getAnswerModel()` in `src/index.ts`). ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - pass `01M5JBDQMSX222282AQPAJJJGA` · valid: The exact-grounded sentence copies lookup -> sonar-pro and answer -> sonar-reasoning-pro. The reviewer identifies registerLookupTool in src/tools/lookup.ts and registerAnswerTool in src/tools/answer.ts as the authorities and lists the same mappings there, with no exclusive members. This satisfies the required comparison and establishes a medium maintenance defect: the prose independently repeats repository-selected models, rather than a vendor-defined set. The reported MCP interface gives callers no model-selection action requiring those names. The pointer exception does not exempt the members stated beside the pointers. The reported nonexistent helpers also make the current navigation misleading. Preserve the purpose that models are configured per tool and point to the actual registration functions; exact model names are unnecessary for that implementation-orientation task. The earlier adjudication supplies no concrete refutation, and the current evidence independently supports the conclusion. - disposition: none > Changing the Perplexity model selected by a tool requires a second manual edit to this implementation overview. Readers looking for the configuration are also directed to getLookupModel() and getAnswerModel() in src/index.ts, neither of which exists. > > The authority is the options passed to performChatCompletion in registerLookupTool in src/tools/lookup.ts and registerAnswerTool in src/tools/answer.ts. The source defines the mappings lookup → sonar-pro and answer → sonar-reasoning-pro. The prose covers exactly lookup → sonar-pro and answer → sonar-reasoning-pro; neither list has an exclusive member. These are selections made by this repository, rather than a description of the vendor's available models. > > Replace this sentence with: “The model and search-context settings are defined in registerLookupTool in src/tools/lookup.ts and registerAnswerTool in src/tools/answer.ts.” This preserves the implementation reader's task of finding and changing the settings without maintaining another model inventory. It follows writing-for-agents' One Idea, One Place guidance; callers do not select these models through the MCP interface, so exact model names are not needed to invoke either tool. > > I read README.md, src/index.ts, src/server.ts, and both tool registration modules and traced their calls to performChatCompletion. This is a static source comparison. A data flow deriving this README sentence from the tool definitions, or a caller-facing requirement for the fixed model identities, would refute the unnecessary-copy finding; neither is present in the examined call path. ### medium — The documented Node minimum is lower than the package requirement - claim: `01M5JBCE9G9G8KM21N9NMF6GZD` - anchor: `README.md` (snippet) ``` - Node.js v24.0.0 or newer ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - pass `01M5JBDQMSX222282AQPAJJJGA` · valid: The exact-grounded README prerequisite allows Node.js 24.0.0 or newer. The reviewer quotes the contrasting package.json engines.node declaration as >=24.15.0. Versions from 24.0.0 through 24.14.x therefore satisfy the documentation but fall outside declared support. This is a concrete documentation mismatch; it does not depend on demonstrating a runtime crash, and installation rejection is explicitly conditional on engine enforcement. The setup reader needs the supported minimum to choose a runtime, so retaining the exact prerequisite serves a distinct task and is permitted by the task-critical-information exception. Align the README minimum with 24.15.0 or derive it from the manifest. Medium severity is appropriate. Reassessing the historical claim reveals no counterevidence or changed contract that defeats the current comparison. - disposition: none > A user following Requirements can choose Node 24.0.0 even though this package declares that runtime unsupported. The README says “Node.js v24.0.0 or newer”, whereas package.json sets engines.node to “>=24.15.0”. Readers on Node 24.0 through 24.14 can therefore complete the documented prerequisite and still encounter an engine warning or rejection when installing with engine enforcement. > > Change the requirement to “Node.js v24.15.0 or newer”. This is the smallest correction that preserves the setup reader's ability to choose a runtime before installation. The exact prerequisite belongs on this surface: a bare pointer to package.json would require an extra lookup to decide whether installation is supported. It follows the writing guides' requirements for verifiable claims and task-sufficient prerequisites. > > I compared the README Requirements section with package.json's engines field. This establishes a documentation/manifest mismatch by static inspection; I did not test execution on older Node releases or claim a particular runtime crash. A change to the governing engine constraint or evidence that the README is intentionally documenting a different supported artifact would refute the mismatch; neither appears in the reviewed setup instructions. ### low — The prompt references send readers to a file that does not define them - claim: `01M5JBD1PQTNF40N2JE7YJEG5Q` - anchor: `README.md` (snippet) ``` The lookup tool uses a compact fact‑extraction prompt focused on code/docs facts (see `LOOKUP_SYSTEM_PROMPT` in `src/index.ts`). The answer tool uses a technical decision/analysis prompt tailored for migrations and architecture choices (see `ANSWER_SYSTEM_PROMPT` in `src/index.ts`). ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - pass `01M5JBDQMSX222282AQPAJJJGA` · valid: The exact-grounded passage locates LOOKUP_SYSTEM_PROMPT and ANSWER_SYSTEM_PROMPT in src/index.ts. The reviewer supplies a concrete contradictory trace: src/prompts.ts defines both constants, the lookup and answer tool modules import them from ../prompts.js and pass them as the system option to performChatCompletion, and src/index.ts has neither definitions nor re-exports. That account explains why a contributor following either reference reaches the wrong file; it is more than a bare assertion of inspection. Nothing in the batch contradicts this trace, and the historical adjudication adds no applicable refutation. Changing both references to src/prompts.ts while retaining the tool-purpose explanations repairs the navigation without duplicating prompt contents. Low severity is appropriate. - disposition: none > A contributor trying to inspect or tune either system prompt is sent to src/index.ts, which contains CLI startup rather than the prompt definitions. Both named constants are defined in src/prompts.ts. > > The overview explicitly directs readers to LOOKUP_SYSTEM_PROMPT and ANSWER_SYSTEM_PROMPT “in src/index.ts”. In the actual call path, src/tools/lookup.ts and src/tools/answer.ts import those constants from ../prompts.js and pass them as the system option to performChatCompletion. > > Change both source references to src/prompts.ts, retaining the explanations that lookup extracts documentation facts and answer supports technical decisions. That preserves the overview's reader task and the existing useful pointer structure without copying the prompts or their contents. This follows the writing guides' precise-language and One Idea, One Place guidance. > > I read the README overview, src/index.ts, src/prompts.ts, and both tool modules. This is a static trace, not a runtime test. Definitions or re-exports of these constants in src/index.ts would refute the claim; that file has neither. ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (0) - duplicate-of (0) - unadjudicated (0) ## Coverage Coverage pass: 01M5JB5JMSJDHNZ315JAARGZEJ Accounting: complete Slot health: healthy | lens | part | arm | unit status | runs | loss | | --- | --- | --- | --- | --- | --- | | restated-sets | whole | default | no-claims | 1 | no | | general-bug | whole | default | no-claims | 1 | no | | writing-quality | docs-and-workflows | default | claims-emitted | 1 | no | | project-docs | whole | default | no-claims | 1 | no | - test-trimming — skipped-by-dispatch: no test files changed - unix-cli — skipped-by-dispatch: changes are CI workflows, docs, and small script edits; no CLI interface changes evident - use-effect — skipped-by-dispatch: no React code changed; only workflows, docs, and build scripts - react — skipped-by-dispatch: no React components or manifests changed

🚀 1

jercik referenced this pull request 2026-10-22 17:29:41 +00:00

docs: fix stale README Node version and source pointers #3

jercik commented 2026-10-22 17:37:45 +00:00

Author

Owner

• Copy link
• Copy Markdown

Replying to review 01M5JA2WK3RYV0XTRZ7MSVHDMZ (summary #177976, head e6932044)

• Node.js prerequisite (claim 01M5JA8ETMWRC2KHG7163668A8), prompt source pointers (claim 01M5JA8YM5M7KK5WQRWCREVWN7) and the hand-copied tool-to-model mapping (claim 01M5JA9GZB98TPGDVEAJYW34PW): all valid, and all in README text this PR did not change. The README says v24.0.0 where engines.node is >=24.15.0, points at src/index.ts for prompts that live in src/prompts.ts, and names getLookupModel()/getAnswerModel(), which do not exist (the models are literals in src/tools/lookup.ts and src/tools/answer.ts). Tracked in #3, whose edits sit outside this PR's hunks.
• Unadjudicated claim 01M5JA73P6YNA5B5XR5ZA4M0TV (the repoq guidance counts the CLI's write commands): not a defect in this PR. The sentence "It also carries one write verb: pr create" is in the generated AGENTS.md/CLAUDE.md, which align regenerated here from the shared rule repoq/repoq-usage.md; generated files are not edited by hand. The count is accurate today: repoq registers pr create as its only write command (src/cli/register-pr-command.ts). If repoq gains another write verb, the shared rule in the align repository needs the update, which is outside these PRs.

> Replying to review `01M5JA2WK3RYV0XTRZ7MSVHDMZ` (summary #177976, head e6932044) - Node.js prerequisite (claim `01M5JA8ETMWRC2KHG7163668A8`), prompt source pointers (claim `01M5JA8YM5M7KK5WQRWCREVWN7`) and the hand-copied tool-to-model mapping (claim `01M5JA9GZB98TPGDVEAJYW34PW`): all valid, and all in README text this PR did not change. The README says `v24.0.0` where `engines.node` is `>=24.15.0`, points at `src/index.ts` for prompts that live in `src/prompts.ts`, and names `getLookupModel()`/`getAnswerModel()`, which do not exist (the models are literals in `src/tools/lookup.ts` and `src/tools/answer.ts`). Tracked in https://code.j4k.dev/j4k-oss/perplexity-agent-mcp/pulls/3, whose edits sit outside this PR's hunks. - Unadjudicated claim `01M5JA73P6YNA5B5XR5ZA4M0TV` (the repoq guidance counts the CLI's write commands): not a defect in this PR. The sentence "It also carries one write verb: `pr create`" is in the generated `AGENTS.md`/`CLAUDE.md`, which align regenerated here from the shared rule `repoq/repoq-usage.md`; generated files are not edited by hand. The count is accurate today: repoq registers `pr create` as its only write command (`src/cli/register-pr-command.ts`). If repoq gains another write verb, the shared rule in the align repository needs the update, which is outside these PRs.

jercik added 1 commit 2026-10-22 17:39:11 +00:00

docs: tell existing global installs to uninstall first and keep the registry line ... d503ab850a

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

jercik commented 2026-10-22 17:48:03 +00:00

Author

Owner

• Copy link
• Copy Markdown

Replying to review 01M5JB47ECFSH4WYG74CYNEJQP (summary #177976, head d503ab85)

All three findings (model-selection copy 01M5JBC048B6JAF8VJZTBXWH6B, Node minimum 01M5JBCE9G9G8KM21N9NMF6GZD, prompt source pointers 01M5JBD1PQTNF40N2JE7YJEG5Q) are valid, concern README text this PR did not change, and are already fixed on main in 95a19e6 (#3). This review ran on a head that does not contain that commit.

> Replying to review `01M5JB47ECFSH4WYG74CYNEJQP` (summary #177976, head d503ab85) All three findings (model-selection copy `01M5JBC048B6JAF8VJZTBXWH6B`, Node minimum `01M5JBCE9G9G8KM21N9NMF6GZD`, prompt source pointers `01M5JBD1PQTNF40N2JE7YJEG5Q`) are valid, concern README text this PR did not change, and are already fixed on `main` in 95a19e6 (https://code.j4k.dev/j4k-oss/perplexity-agent-mcp/pulls/3). This review ran on a head that does not contain that commit.

jercik merged commit 46808e43fe into main 2026-10-22 17:49:50 +00:00

jercik deleted branch chore/remove-npm-mirror 2026-10-22 17:49:50 +00:00

jercik referenced this pull request from a commit 2026-10-22 17:49:51 +00:00

chore: remove npm-mirror leftovers and document the scoped package (#2)

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

j4k-oss/perplexity-agent-mcp!2

No description provided.