Skip to content

refactor: enhance documentation and address code quality issues#3

Merged
simonCatBot merged 4 commits intomasterfrom
refactor/enhance-documentation
Mar 27, 2026
Merged

refactor: enhance documentation and address code quality issues#3
simonCatBot merged 4 commits intomasterfrom
refactor/enhance-documentation

Conversation

@simonCatBot
Copy link
Copy Markdown
Owner

@simonCatBot simonCatBot commented Mar 27, 2026

Summary

Documentation overhaul + five targeted code quality improvements identified during a project audit.

Changes

Documentation

  • CONTRIBUTING.md — Fully rewritten. Added prerequisites (Node ≥20.9.0), a dedicated troubleshooting section covering native dependency failures, SQLite errors, Node version mismatches, and the OPENCLAW_SKIP_NATIVE_RUNTIME_VERIFY escape hatch. Expanded the scripts table with descriptions and clarified when to run cleanup:ux-artifacts.
  • .github/ISSUE_TEMPLATE/issue.md — Added "Gateway version" field to the environment section for better reproducibility.
  • next.config.ts — Added // TODO comment explaining why ignoreBuildErrors: true is temporarily needed and confirming that npm run typecheck (CI) still catches type errors.

Code quality

  • package.json — Pinned @multiavatar/multiavatar GitHub dependency to commit SHA a938f6f to prevent breakage if the upstream repo reorganizes or deletes the default branch.
  • src/lib/controlplane/_better-sqlite3-require.ts (new) — Isolated the createRequire/better-sqlite3 CJS→ESM bridge into a single, clearly-documented shim. Makes the module-system boundary explicit and easy to refactor later.
  • src/lib/rate-limit.ts (new) — Simple in-process sliding-window rate limiter. Per-IP, 60 req/s default, 30 req/s for chat.send. Includes X-RateLimit-* response headers and full test coverage.
  • src/lib/controlplane/intent-route.ts — Wired in the rate limiter; all intent responses now carry X-RateLimit-Limit and X-RateLimit-Remaining headers.
  • src/app/api/intents/chat-send/route.ts — Added rate limit check (30 req/s, higher than the 60 req/s default to accommodate real-time typing without false positives).
  • tests/unit/rateLimit.test.ts (new) — Covers: allow under limit, block over limit, per-key isolation, window expiry reset, defaults, and rateLimitRemaining correctness.

Testing

  • npm run lint
  • npm run typecheck
  • npm run test
  • npm run e2e (requires npx playwright install)

AI-assisted

Yes — audit performed by Miaman (OpenClaw agent). Full audit notes available on request.

Miaman (OpenClaw Agent) added 4 commits March 26, 2026 22:24
refactor: enhance documentation and address code quality issues
bf99a51 
Documentation:
- CONTRIBUTING.md: rewrite with clear prerequisites (Node ≥20.9.0),
  full troubleshooting section for native deps, SQLite errors, Node
  version mismatches, and the OPENCLAW_SKIP_NATIVE_RUNTIME_VERIFY flag.
  Expand scripts table and clarify UX audit cleanup step.
- .github/ISSUE_TEMPLATE/issue.md: add Gateway version field to
  environment section for better reproducibility.
- next.config.ts: add TODO comment explaining why ignoreBuildErrors is
  temporarily true and noting that npm run typecheck still catches
  errors in CI.

Code quality:
- package.json: pin @multiavatar/multiavatar GitHub dependency to
  specific commit SHA (a938f6f) to prevent drift if the repo is
  reorganized.
- src/lib/controlplane/projection-store.ts: replace inline
  createRequire/createRequire pattern with a dedicated, documented
  ESM/CJS shim at _better-sqlite3-require.ts. Makes the module-system
  boundary explicit and easy to find.
- src/lib/rate-limit.ts: new file — simple in-process sliding-window
  rate limiter for intent routes. Per-IP, 60 req/s default, 30 req/s
  for chat.send. Includes test coverage.
- src/lib/controlplane/intent-route.ts: wire in rate limiter; add
  X-RateLimit-Limit / X-RateLimit-Remaining response headers to all
  intent responses.
- src/app/api/intents/chat-send/route.ts: add rate limit check
  (30 req/s, higher than default to accommodate real-time typing).
- tests/unit/rateLimit.test.ts: new — covers allow/block/per-key
  isolation/window-expiry/defaults.
docs: complete rewrite of README
bdd5bd4
docs: substantially enhance README
14856a9 
- Add Key Concepts section (Gateway, Agent, Session, Intent, Outbox)
- Expand Features with detailed descriptions for each tab area,
  including specific controls and behaviors
- Add a Gateway URL reference table as the canonical home for
  every scenario (local, Tailscale, SSH tunnel, cloud TLS)
- Add Tailscale binding instructions with gateway.bind config tip
- Add Permissions at a Glance table covering command mode, sandbox
  mode, workspace access, and tools profile
- Add critical warning about workspaceAccess=ro also disabling
  write/edit/apply_patch tools inside sandbox (a non-obvious gotcha)
- Expand Troubleshooting with sections for 401 auth split
  (gateway token vs ROCclaw access token), agent not responding,
  and sandbox not working
- Point to the full permissions doc for the sandbox debug checklist
- Remove stale Quick Start section, fold its content into the
  reorganized structure
docs: rewrite all documentation to be precise and task-oriented
b67db0c 
README:
- Cut from 13KB to 6KB. Remove redundant content.
- Remove Scripts table (belongs in CONTRIBUTING.md).
- Remove Permissions at a Glance table (full model in permissions doc).
- Remove ASCII UI art (goes stale, not useful for technical orientation).
- Lead with how to connect and how it works, then features, then
  troubleshooting. Flat and direct.
- Remove dead 'color-system.md' link (file does not exist).
- Add Document Map table to orient readers by task.

docs/ui-guide.md:
- Full rewrite. Remove all implementation/state descriptions.
- Organize by UI surface: connection screen, agents tab, chat panel,
  settings sidebar (four tabs), system metrics, tokens.
- Remove stale 'coming soon' items (heartbeats, skills, browser).
- Remove references to old onboarding flows.
- Remove 'core rule' about localhost (no longer confusing in practice).
- Every control in the chat header and settings tabs is now in a table.

docs/pi-chat-streaming.md:
- Cut from 1.4KB to 1.6KB. Rename from 'PI Chat Streaming' to
  'Chat Streaming' — 'PI' is internal terminology.
- Keep the transport model, reconnect/replay, history, and degraded
  behavior sections. Remove no longer accurate internal routing hints.

docs/permissions-sandboxing.md:
- Cut from 18KB to 5.8KB.
- Lead with mental model (UI vs enforcement point) before diving in.
- Remove the full code entry point inventory (code archaeology).
- Remove the Glossary (duplicated in old README, now removed).
- Keep: sandbox modes, workspace access (with ro warning), tool policy
  layering, exec approvals, session exec settings, debug checklist.
- Remove: mermaids, upstream file paths, implementation references.
- New 'Debugging: when something feels wrong' section covers the
  three common failure modes with clear triage steps.

ARCHITECTURE.md:
- Remove 'OpenClaw Studio' throughout, replace with 'rocCLAW'.
- Remove 'Removed legacy surfaces' section and guardrails about
  /api/gateway routes (archaeology, not useful in a current doc).
- Reformat as a reference document: table of modules, table of routes,
  clear error semantics, compact guardrails that explain _why_ each
  constraint exists.
@simonCatBot simonCatBot merged commit bde30be into master Mar 27, 2026
@simonCatBot simonCatBot deleted the refactor/enhance-documentation branch March 27, 2026 08:02
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@simonCatBot