docs: sync pkc-js ecosystem docs with current code

[Rinse12]

Summary

Four docs had drifted from upstream code in ../pkc-js, ../bso-resolver, ../evm-contract-challenge, and @bitsocial/bitsocial-cli. This patches each one in place. The package-mirror pages are still hand-maintained — see follow-up issue for the automation question.

• docs/permissionless-public-rpc.md — RPC method names in the proposed permission bundle now match what pkc-js/src/rpc/src/index.ts:210–233 actually registers: fetchContent → fetchCid, resolveAuthorAddress → resolveAuthorName, communityListSubscribe → communitiesSubscribe. The other 13 method names already matched.
• docs/infrastructure/bso-resolver.md — license GPL-2.0-only → GPL-3.0-or-later (per bso-resolver/package.json), resolve() return shape clarified to a BsoResolveResult object containing publicKey, and the pkc-js integration snippet uses the real async factory shape (import PKC from "@pkcprotocol/pkc-js"; const pkc = await PKC({ nameResolvers })) instead of a fake new Pkc({...}) constructor.
• docs/developer-tools/cli.md — every shell example now invokes the actual binary bitsocial (the package is @bitsocial/bitsocial-cli but its bin resolves to bitsocial, per the installed package's package.json). Repo and package-name references stay as-is.
• docs/anti-spam/evm-contract-call.md — adds the missing rpcUrls option to the configuration table; the actual challenge in evm-contract-challenge/src/evm-contract-challenge.ts:32 defines six options and the docs only listed five.

i18n copies under docs/i18n/ are not touched — the project regenerates those via scripts/translate-docs.py as a separate step.

Test plan

• yarn lint (0 errors, pre-existing warnings only)
• yarn typecheck (exit 0)
• yarn format ran on the four files (oxfmt aligned the column widths in the evm-contract-call table)
• yarn docs:build:verify succeeds, Pagefind index regenerated (35 pages)
• Spot-checked RPC method names against grep -nE "rpcWebsocketsRegister" pkc-js/src/rpc/src/index.ts
• Spot-checked bitsocial --help against @bitsocial/bitsocial-cli/dist/cli/commands/
• Re-run scripts/translate-docs.py to refresh docs/i18n/** (separate step, intentionally out of scope)

Summary by CodeRabbit

• Documentation

  • Added optional JSON-RPC endpoint configuration for EVM contract calls on target chains.
  • Updated CLI command examples to use current binary naming conventions.
  • Improved resolver documentation with clarity on resolution sources and updated integration examples.

• API Updates

  • Permission capability keys renamed for consistency: fetchCid, resolveAuthorName, and communitiesSubscribe.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
bitsocial-docs	Ready	Preview, Comment	Apr 30, 2026 5:45am
bitsocial-web	Ready	Preview, Comment	Apr 30, 2026 5:45am

[coderabbitai]

Warning

Rate limit exceeded

@tomcasaburi has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 59 minutes and 22 seconds before requesting another review.

To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 58007b3c-fc50-4a07-a0f2-82bc30846be0

📥 Commits

Reviewing files that changed from the base of the PR and between e88bf80 and 133ae21.

📒 Files selected for processing (1)

• docs/infrastructure/bso-resolver.md

📝 Walkthrough

Walkthrough

Documentation updates across multiple files address API naming inconsistencies, license metadata, configuration additions, and integration pattern clarifications. Changes include configuration table enhancements, CLI command name standardization, resolution source corrections, method signature updates, and async API adoption patterns.

Changes

Cohort / File(s)	Summary
Configuration Documentation docs/anti-spam/evm-contract-call.md	Added optional rpcUrls field to Configuration Options table for supplying comma-separated JSON-RPC endpoints.
CLI Command References docs/developer-tools/cli.md	Updated all CLI command examples to use bitsocial binary name instead of bitsocial-cli.
Infrastructure & License Updates docs/infrastructure/bso-resolver.md	Updated license identifier from GPL-2.0-only to GPL-3.0-or-later, shifted resolution documentation from ENS TXT records to Bitsocial TXT records, expanded resolve method contract to include publicKey field, and updated pkc-js integration to use async factory API pattern instead of constructor.
Permission Bundle API docs/permissionless-public-rpc.md	Renamed capability keys in PermissionBundle.methods: fetchContent → fetchCid, resolveAuthorAddress → resolveAuthorName, communityListSubscribe → communitiesSubscribe.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

Possibly related issues

• Issue #5: This PR directly addresses documented API naming discrepancies (fetchContent/fetchCid, resolveAuthorAddress/resolveAuthorName, communityListSubscribe/communitiesSubscribe), license metadata drift (GPL-2.0-only vs. GPL-3.0-or-later), and stale integration examples (constructor vs. async factory) that were flagged in the related issue.

Poem

🐰 Words were tangled, names askew,
GPL versions and APIs too,
A dash of async, some RPC light,
The docs now dance—all clear and bright! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: sync pkc-js ecosystem docs with current code' accurately summarizes the main objective of the pull request, which is to align four documentation files with upstream code changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/docs/sync-with-pkc-js

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 59 minutes and 22 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/infrastructure/bso-resolver.md`:
- Line 12: Update the SPDX license identifier string used in the documentation
by replacing the current "GPL-3.0-or-later" token with the correct upstream
identifier "GPL-3.0"; locate the line that reads "**License**: GPL-3.0-or-later"
in the bso-resolver docs and change it to "**License**: GPL-3.0" so the README
matches the upstream repository's license.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0d168bf0-638b-4977-9c86-4f4056b1c443

📥 Commits

Reviewing files that changed from the base of the PR and between 8189806 and e88bf80.

📒 Files selected for processing (4)

• docs/anti-spam/evm-contract-call.md
• docs/developer-tools/cli.md
• docs/infrastructure/bso-resolver.md
• docs/permissionless-public-rpc.md

[tomcasaburi]

Addressed the valid review finding in the latest commit: the BSO Resolver license now matches the upstream GitHub license endpoint (GPL-3.0). Local verification: yarn build:verify, yarn lint, yarn typecheck, and yarn oxfmt --check docs/infrastructure/bso-resolver.md. The full repo yarn format:check is currently blocked by unrelated pre-existing formatting issues in repo-managed skill files outside this PR; the touched docs file passes the formatter.