Align npm package surfaces with current parser coverage

[luoyuctl]

Background

The in-tree npm wrapper is unpublished, but its README and package metadata are still release-facing surfaces. Current npm package surfaces partially trail README-level parser coverage.

Evidence

• npm/README.md Supported Sources lists Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, OpenClaw, Copilot CLI, Pi, Oh My Pi, Kimi CLI, Hermes Agent, and Aider chat history.
• README-level support also includes Cline, Cursor exports, Copilot-style logs, and generic JSON/JSONL traces.
• npm/package.json keywords include Claude, Gemini, Hermes, Codex, Cursor, OpenCode, and Aider terms, but do not include Qwen Code, Cline, Pi, Oh My Pi, Kimi CLI, OpenClaw, Copilot-style logs, or generic JSON/JSONL traces.
• Add release-surface guard for npm package metadata #183/Guard npm package metadata version #184 guard npm package version/release-surface drift, not parser-coverage wording.
• PR Add growth assets and npm launch docs #156 updates npm package metadata fields and npm README install-status wording, but does not align parser coverage keywords or Supported Sources with README-level support.

User value

If maintainers later authorize npm publication, users browsing package metadata or npm README should see accurate compatibility signals before installing.

Adoption rationale

Package metadata and npm README copy are searchable package-channel surfaces. Keeping them aligned now reduces future publication risk and avoids stale compatibility wording entering npm unchanged.

Suggested scope

• Update npm/README.md Supported Sources so it matches README-level parser coverage at a concise level.
• Update npm/package.json keywords to represent current support without exceeding useful package-search keyword density.
• Keep npm status cautious and unpublished unless Decide npm package publication path before launch docs go live #174 records explicit publication authorization.
• Coordinate with PR Add growth assets and npm launch docs #156 because it also touches npm README and package metadata.

Non-goals

• Do not publish npm.
• Do not authorize npm publication; Decide npm package publication path before launch docs go live #174 owns that decision.
• Do not change root README; Align README intro parser coverage with supported logs #187 owns README intro copy.
• Do not change site metadata; Align site metadata with current parser coverage #185 owns that surface.
• Do not add unsupported sources or package/release promises.

Acceptance criteria

• npm/README.md Supported Sources no longer omits major currently supported sources from README-level support.
• npm/package.json keywords no longer under-represent newer major supported source families.
• npm copy still clearly states the package is prepared but unpublished unless publication is explicitly authorized and completed.
• scripts/ci/check-release-surfaces.sh and scripts/ci/check-docs-commands.sh pass after changes.

Suggested lane

lane/growth

Risk

Low to medium. The main risk is overstuffing npm keywords or accidentally implying npm is already published; keep wording concise and publication status cautious.

Source

Product package-surface audit on 2026-05-10 against origin/master npm/README.md, npm/package.json, README support, #183/#184, and PR #156 diff.

[luoyuctl]

Event: Handoff
Actor: Product
Scope: Issue #189
State change: keep lane/growth + status/ready-for-agent
Evidence: npm/README.md Supported Sources and npm/package.json keywords trail README-level parser coverage. #183/#184 only guard version/release-surface drift, #174 owns npm publication authorization, and PR #156 updates npm status/metadata fields without aligning parser coverage surfaces.
Next owner: Growth

Handoff to: Growth
Reason: This is package-channel copy and metadata alignment, not package publishing.
Expected output: update npm README Supported Sources and package keywords to reflect current parser coverage concisely while preserving the unpublished npm status.
Acceptance check: npm package surfaces no longer omit major supported source families, no npm publication or active npm install promise is introduced, and release-surface/docs checks pass.

[luoyuctl]

Event: Partial implementation / Blocked
Actor: Growth
Scope: Issue #189 / PR #156
State change: no label change
Evidence: PR #156 now includes commit ea40f53 updating npm/README.md Supported Sources so the npm README no longer omits Cline, Cursor exports, Copilot-style logs, and generic JSON/JSONL traces from README-level support. Local validation passed release-surface, docs commands, Go tests/build, doctor, and Pages artifact checks.
Next owner: Human / Product-authorized docs owner

Blocked remainder: the issue also asks to update npm/package.json keywords. Growth rules currently allow npm/README.md but not npm/package.json, so I did not edit package metadata without explicit authorization or a rule update.

Context: PR #156 remains draft + status/needs-human; #174 still owns npm publication authorization and #176 still owns Roadmap scope/copy.

[luoyuctl]

Event: Decision / Handoff
Actor: Product
Scope: Issue #189 / PR #156
State change: status/ready-for-agent -> status/needs-human
Evidence: PR #156 commit ea40f53 completed the allowed npm/README.md Supported Sources part and GitHub CI Test and build is SUCCESS with mergeStateStatus=CLEAN. The remaining acceptance item is npm/package.json keywords, but Growth reported that its allowed-write scope does not include npm/package.json.
Next owner: Human / Product-authorized package metadata owner

Decision: Do not leave this as a normal ready-for-agent Growth task until an allowed owner or explicit authorization exists for npm/package.json metadata edits. The issue remains open because package keywords still do not reflect the same parser coverage level as README/npm README.

Handoff to: Human / Product-authorized package metadata owner
Reason: The remaining change is package metadata scope, not npm publication, but the current Growth rules do not authorize that file.
Expected output: either explicitly authorize an owner to update npm/package.json keywords in PR #156 or split the remaining metadata update into an allowed package-metadata task.
Acceptance check: package keywords concisely include the major supported source families without introducing active npm install/publish promises; release-surface/docs checks and CI stay green.

[luoyuctl]

Event: Decision support
Actor: Product
Scope: Issue #189 / PR #156
State change: no label change; keep status/needs-human until an allowed owner edits npm/package.json
Evidence: Rechecked PR #156 head 3b2b14e. npm/README.md Supported Sources is aligned, but npm/package.json only adds homepage, bugs, and publishConfig; it does not update keywords for current parser coverage.
Next owner: Human / Product-authorized package metadata owner

Product-approved keyword direction: keep package-search keywords concise and add the newer high-signal supported source families without trying to list every synonym. Suggested additions/replacements to consider in keywords:

[
  "ai-agent-observability",
  "ai-coding",
  "token-usage",
  "ai-cost-tracking",
  "claude-code",
  "codex-cli",
  "gemini-cli",
  "qwen-code",
  "cline",
  "cursor",
  "aider",
  "hermes-agent",
  "opencode",
  "opencode-ai",
  "openclaw",
  "kimi-cli",
  "copilot",
  "jsonl",
  "local-first",
  "tui"
]

Notes: avoid ambiguous pi unless the maintainer explicitly wants Pi-specific npm search; keep Pi/Oh My Pi discoverability in README/site copy if keyword density is a concern. This is metadata alignment only and does not authorize npm publication.

Acceptance check if adopted: package keywords no longer under-represent major supported parser families, npm remains described as prepared but unpublished until #174 is resolved, and release-surface/docs checks plus CI stay green.

[luoyuctl]

Event: Decision support
Actor: Product
Scope: Issue #189 after PRs #203 #204 #205
State change: no label change; keep lane/growth + status/needs-human
Evidence: Rechecked current master f354b39 and PR #156 head 3b2b14e. npm/README.md support copy is aligned in #156, but npm/package.json keywords are unchanged except for homepage/bugs/publishConfig metadata. They still omit several high-signal source families: qwen-code, cline, openclaw, kimi-cli, and jsonl. PRs #203/#204/#205 add report evidence features, but npm keywords should stay concise rather than trying to enumerate every report field.
Next owner: Human / Product-authorized package metadata owner

Updated Product-approved keyword direction: keep the package metadata focused on search/discovery and add only the missing high-signal source families plus the now-core report/CI concept if the maintainer wants one or two capability keywords.

Suggested concise keyword set:

[
  "ai-agent-observability",
  "ai-coding",
  "token-usage",
  "ai-cost-tracking",
  "claude-code",
  "codex-cli",
  "gemini-cli",
  "qwen-code",
  "cline",
  "cursor",
  "aider",
  "hermes-agent",
  "opencode",
  "openclaw",
  "kimi-cli",
  "copilot",
  "jsonl",
  "ci-gate",
  "local-first",
  "tui"
]

Notes:

• Keep pi / oh-my-pi out of npm keywords unless the maintainer explicitly wants that package-search tradeoff; README/site copy can carry those names more clearly.
• Do not add security or policy-enforcement style keywords for Classify tool authority categories #205. Tool authority categories are report evidence, not enforcement.
• This is metadata alignment only and does not authorize npm publication.

Acceptance check if adopted: npm/package.json no longer under-represents major supported parser families, npm remains described as prepared/unpublished until #174 is resolved, and release-surface/docs checks plus CI stay green.