docs: say why the @j4k-oss registry mapping is required #5

Merged

jercik merged 1 commit from docs/npm-scope-ownership into main 2026-10-23 07:17:18 +00:00

Conversation 2 Commits 1 Files changed 2 +3 -3

jercik commented 2026-10-23 07:09:39 +00:00

Owner

• Copy link
• Copy Markdown

The @j4k-oss scope on npmjs is now ours and holds no packages, so the README no longer calls its owner unconfirmed or says npm could fetch another owner's package. The registry mapping is still required, because without it npm looks on npmjs, finds nothing, and fails with a 404. The README also calls the unscoped perplexity-agent-mcp deprecated instead of frozen.

AGENTS.md is regenerated from align 9.0.6. The only change is the same reason in the repoq rule.

🤖 Generated with Claude Code

The `@j4k-oss` scope on npmjs is now ours and holds no packages, so the README no longer calls its owner unconfirmed or says `npm` could fetch another owner's package. The registry mapping is still required, because without it `npm` looks on npmjs, finds nothing, and fails with a 404. The README also calls the unscoped `perplexity-agent-mcp` deprecated instead of frozen. `AGENTS.md` is regenerated from align 9.0.6. The only change is the same reason in the repoq rule. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

jercik added 1 commit 2026-10-23 07:09:40 +00:00

docs: say why the @j4k-oss registry mapping is required ... 4b68d39c1b

The @j4k-oss scope on npmjs is now ours and holds no packages. The
registry mapping is still required because every @j4k-oss package exists
only on the Forge: without it, npm looks on npmjs, finds nothing, and
fails with a 404. The unscoped npmjs packages are deprecated.

Regenerate AGENTS.md from align 9.0.6 for the matching repoq rule.

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

forgejo-actions commented 2026-10-23 07:16:32 +00:00

• Copy link
• Copy Markdown

Review 01M5KSG6AQFZSAV8QSYPF35MQX — head 4b68d39c1be5ebe49ec5f143cadce975f62f22e6

Review — j4k-oss/perplexity-agent-mcp @ 1d27a2320e

Scope: diff against base tree ba99a4f64451
Status: dispatched — coverage complete (9/9 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 (1)

medium — The introduction repeats the complete tool inventory from “How it works”

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

An opinionated, coding-specialized, Model Context Protocol server that integrates Perplexity AI's Sonar models into AI coding assistants like Claude Code or Codex CLI. It's deliberately lean and adds very few tokens to your context. It provides two specialized tools—`lookup` for instant fact-checking of API syntax and documentation details, and `answer` for comprehensive research with actionable recommendations.

• lens: writing-quality · arm: default
• verdicts: 1 valid / 0 invalid / 0 uncertain
  • pass 01M5KSQ5JSJ0VNYFJYEECP5RKJ · valid: Restated-set claim that meets the guideline's evidence bar. The grounded exact anchor shows the introduction giving a count ('two specialized tools') and naming both members, lookup and answer. The body names the source (createServer in src/server.ts, which calls registerLookupTool and registerAnswerTool, defined in src/tools/lookup.ts and src/tools/answer.ts) and lists its members: lookup and answer. The copy names lookup and answer, so no member appears in only one list, and the count of two matches. Because the copy still agrees with its source, medium is correct, not high. No exception applies. The introduction is not derived from the registration code, and it is not a table of contents, a dated record, or a list of examples. It also has no task of its own that needs the members: by the reviewer's account, the 'How it works' section already gives each tool's name and purpose for a reader choosing a tool, and the claim keeps that section. Removing the inventory loses nothing, because 'How it works' still says 'only two tools', which supports the 'deliberately lean' point. The proposed replacement keeps the introduction's purpose and adds a section pointer, which fits One Idea, One Place and 'state each fact once'. That section's wording is the reviewer's account and is not grounded. Under the restated-sets rule, that account is acceptable evidence and does not affect the defect itself.
• disposition: none

The introduction creates another place to update whenever the tool set changes, without helping readers make a different decision from the tool descriptions under “How it works.” Both passages enumerate the same complete set, so a tool addition can silently leave the introduction stale.

The authority is createServer in src/server.ts, which calls registerLookupTool and registerAnswerTool. Their definitions in src/tools/lookup.ts and src/tools/answer.ts register the members lookup and answer. The introduction says “two specialized tools” and names lookup and answer; the later section says “only two tools” and describes lookup and answer in bullets. The source and both copies currently agree; no member appears in only one list.

Apply “One Idea, One Place” from writing-for-agents and the human-facing standard to state each fact once. Replace the introduction’s last sentence with: “Use it for source-backed coding facts and research; see ‘How it works’ for help choosing a tool.” Retain the later tool descriptions: readers selecting a tool need its name and purpose, and a pointer into implementation code would not serve that interface task. The replacement preserves the introduction’s purpose and supplies a precise section pointer without maintaining another member list or count.

I read README.md in full and traced createServer through both registration functions. This is a static comparison, not a runtime test. A distinct reader task that requires the same complete inventory in the introduction, or evidence that the introductory inventory is derived from registration code, would refute the unnecessary-copy finding.

Other claims

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

Coverage

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

lens	part	arm	unit status	runs	loss
general-bug	whole	default	no-claims	1	no
writing-quality	whole	default	claims-emitted	1	no
test-trimming	whole	default	no-claims	1	no
restated-sets	whole	default	no-claims	1	no
project-docs	whole	default	no-claims	1	no
unix-cli	whole	default	no-claims	1	no
use-effect	whole	default	no-claims	1	no
module-design	whole	default	no-claims	1	no
react	whole	default	no-claims	1	no

<!-- review:summary --> **Review** `01M5KSG6AQFZSAV8QSYPF35MQX` — head `4b68d39c1be5ebe49ec5f143cadce975f62f22e6` # Review — j4k-oss/perplexity-agent-mcp @ 1d27a2320e6a Scope: diff against base tree `ba99a4f64451` Status: dispatched — coverage complete (9/9 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 (1) ### medium — The introduction repeats the complete tool inventory from “How it works” - claim: `01M5KSPHEYDBDFZ26A6E7XYCSN` - anchor: `README.md` (snippet) ``` An opinionated, coding-specialized, Model Context Protocol server that integrates Perplexity AI's Sonar models into AI coding assistants like Claude Code or Codex CLI. It's deliberately lean and adds very few tokens to your context. It provides two specialized tools—`lookup` for instant fact-checking of API syntax and documentation details, and `answer` for comprehensive research with actionable recommendations. ``` - lens: writing-quality · arm: default - verdicts: 1 valid / 0 invalid / 0 uncertain - pass `01M5KSQ5JSJ0VNYFJYEECP5RKJ` · valid: Restated-set claim that meets the guideline's evidence bar. The grounded exact anchor shows the introduction giving a count ('two specialized tools') and naming both members, lookup and answer. The body names the source (createServer in src/server.ts, which calls registerLookupTool and registerAnswerTool, defined in src/tools/lookup.ts and src/tools/answer.ts) and lists its members: lookup and answer. The copy names lookup and answer, so no member appears in only one list, and the count of two matches. Because the copy still agrees with its source, medium is correct, not high. No exception applies. The introduction is not derived from the registration code, and it is not a table of contents, a dated record, or a list of examples. It also has no task of its own that needs the members: by the reviewer's account, the 'How it works' section already gives each tool's name and purpose for a reader choosing a tool, and the claim keeps that section. Removing the inventory loses nothing, because 'How it works' still says 'only two tools', which supports the 'deliberately lean' point. The proposed replacement keeps the introduction's purpose and adds a section pointer, which fits One Idea, One Place and 'state each fact once'. That section's wording is the reviewer's account and is not grounded. Under the restated-sets rule, that account is acceptable evidence and does not affect the defect itself. - disposition: none > The introduction creates another place to update whenever the tool set changes, without helping readers make a different decision from the tool descriptions under “How it works.” Both passages enumerate the same complete set, so a tool addition can silently leave the introduction stale. > > The authority is createServer in src/server.ts, which calls registerLookupTool and registerAnswerTool. Their definitions in src/tools/lookup.ts and src/tools/answer.ts register the members lookup and answer. The introduction says “two specialized tools” and names lookup and answer; the later section says “only two tools” and describes lookup and answer in bullets. The source and both copies currently agree; no member appears in only one list. > > Apply “One Idea, One Place” from writing-for-agents and the human-facing standard to state each fact once. Replace the introduction’s last sentence with: “Use it for source-backed coding facts and research; see ‘How it works’ for help choosing a tool.” Retain the later tool descriptions: readers selecting a tool need its name and purpose, and a pointer into implementation code would not serve that interface task. The replacement preserves the introduction’s purpose and supplies a precise section pointer without maintaining another member list or count. > > I read README.md in full and traced createServer through both registration functions. This is a static comparison, not a runtime test. A distinct reader task that requires the same complete inventory in the introduction, or evidence that the introductory inventory is derived from registration code, would refute the unnecessary-copy finding. ## Other claims - grounding-pending (0) - ungrounded (0) - rejected (0) - duplicate-of (0) - unadjudicated (0) ## Coverage Coverage pass: 01M5KSG6D6VNF8RPRP4VSAQKQQ Accounting: complete Slot health: healthy | lens | part | arm | unit status | runs | loss | | --- | --- | --- | --- | --- | --- | | general-bug | whole | default | no-claims | 1 | no | | writing-quality | whole | default | claims-emitted | 1 | no | | test-trimming | whole | default | no-claims | 1 | no | | restated-sets | whole | default | no-claims | 1 | no | | project-docs | whole | default | no-claims | 1 | no | | unix-cli | whole | default | no-claims | 1 | no | | use-effect | whole | default | no-claims | 1 | no | | module-design | whole | default | no-claims | 1 | no | | react | whole | default | no-claims | 1 | no |

🚀 1

jercik merged commit cc41657eef into main 2026-10-23 07:17:18 +00:00

jercik deleted branch docs/npm-scope-ownership 2026-10-23 07:17:18 +00:00

jercik referenced this pull request from a commit 2026-10-23 07:17:19 +00:00

docs: say why the `@j4k-oss` registry mapping is required (#5)

jercik referenced this pull request 2026-10-23 08:58:44 +00:00

docs: name the tools in "How it works" only #6

jercik commented 2026-10-23 09:02:46 +00:00

Author

Owner

• Copy link
• Copy Markdown

Replying to review 01M5KSG6AQFZSAV8QSYPF35MQX (summary #179026, head 4b68d39c)

The finding is valid, and it sits in README text this PR did not change. The introduction named and counted both tools, and "How it works" lists the same two (the ones createServer registers in src/server.ts). The copies agreed, but adding a tool would have meant editing both.

Fixed in #6, merged as 4b31ef8: the introduction now states the purpose and links to "How it works", which keeps the tool descriptions.

> Replying to review `01M5KSG6AQFZSAV8QSYPF35MQX` (summary #179026, head 4b68d39c) The finding is valid, and it sits in README text this PR did not change. The introduction named and counted both tools, and "How it works" lists the same two (the ones `createServer` registers in `src/server.ts`). The copies agreed, but adding a tool would have meant editing both. Fixed in https://code.j4k.dev/j4k-oss/perplexity-agent-mcp/pulls/6, merged as 4b31ef8: the introduction now states the purpose and links to "How it works", which keeps the tool descriptions.

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!5

No description provided.