docs: fix stale references and wrong instructions in docs and skills by Makisuo · Pull Request #1065 · MapleTechLabs/maple

Makisuo · 2026-09-25T17:33:20Z

Audited every doc under docs/ and every Maple-owned skill (skills/*, .agents/skills/maple-telemetry-conventions) against the current code, fixed what was wrong, and tightened the prose (em dashes removed).

Docs (53 files)

Paths that moved with Move MCP, chat and investigations into their own Worker (maple-ai) #861: MCP, chat and ChatSession now point at apps/ai.
self-hosted-clickhouse.md rewritten around org_clickhouse_settings. Save only runs SELECT 1; the schema is applied by ClickHouseSchemaApplyWorkflow. Table and MV counts corrected.
attributes.md: service map edges come from joining a client span to its child server span, not from peer.service.
infra.md: EU AI routing (feat(eu): route AI through OpenRouter's EU endpoint and turn chat back on #1052), ARM64 ingest on EC2, the bun dev app list, and moved files.
local-mode.md: an unclean shutdown no longer wipes the store. The default is --on-dirty-store fail.
persistence.md: now describes the PgClient.make client, not the old node-postgres pool.
github-app-setup.md: @maple fix pushes commits, so Contents is read and write. The webhook event list now matches what the code handles.
electric-sync.md: shape registry paths, the investigation_v2 shape, and the real window event names.
OTel spec summaries:
- self-tracing is via @maple-dev/effect-sdk;
- HTTP server 4xx is Unset;
- schema_url scope and resource levels cover different data;
- some ingest 4xx rejections are Error.
Dated investigations and plans keep their findings. Some get a one-line verified status note (e.g. sst-fork-workflow.md is marked obsolete).

Skills

maple-audit MAP-01 to MAP-04, maple-effect-style and maple-telemetry-conventions no longer say peer.service draws map edges.
Language style skills now use real SDK APIs:
- Rust: 0.32 types (SdkTracerProvider), the TLS feature, and HttpBinary;
- Go: otlplog/otlploghttp path;
- Kotlin: opentelemetry-extension-kotlin;
- C#: missing AddSource;
- Node: ESM hook;
- Python: missing import os.
Effect: stacking two tracer layers does not dual-export (the last layer wins). The Coexistence section now says so.
maple-onboard: points at the public @maple-dev/effect-sdk/cloudflare (not the private infra package) and the maple_pk_ key under Settings → Ingestion.
maple-dashboard-widgets/SKILL.md is generated. The fix is in apps/ai/src/mcp/lib/dashboard-schema-doc.ts and the generator, and the file is regenerated from them. The committed file had drifted from its source, which explains the larger diff. The describe_dashboard_schema tool output changes the same way (prose punctuation, and - instead of — for empty table cells).

Verification

bunx vitest run src/mcp/lib/dashboard-schema-doc.test.ts src/mcp/lib/dashboard-docs-drift.test.ts: 76 passed.
bun run --cwd apps/ai mcp:docs --check: up to date.
Measurements, prod counts and upstream spec dates were left as written where the repo can't confirm them.

Follow-ups not in this PR

apps/landing/src/content/docs/concepts/otel-conventions.md still says peer.service draws service map edges.
Stale comments in use-maple-chat.ts (mapleShapeFetch) and .env.example (MAPLE_PG_ELECTRIC_URL).

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by CodeRabbit

Documentation
- Updated guidance across telemetry, OpenTelemetry, service maps, database queries, dashboards, SDKs, APIs, and deployment workflows to reflect current behavior and requirements.
- Expanded setup and troubleshooting details for local development, backups, data sync, ClickHouse, and GitHub integrations.
- Clarified feature availability and status in several product and technical plans.

Audited every doc under docs/ against the current code. Fixed moved paths (MCP, chat and ChatSession now live in apps/ai), renamed symbols, wrong commands and env vars, and claims the code no longer backs (self-hosted ClickHouse settings table, service map edge derivation, local store dirty-shutdown behavior, GitHub App permissions, Postgres client setup, Electric shape registry). Dated investigations and plans keep their findings; some gain a one-line verified status note. Prose tightened throughout and em dashes removed.

Service map edges come from joining a client span to its child server span, not peer.service; the audit, style and telemetry-conventions skills now say so. Language style skills get real SDK APIs and package names (Rust 0.32 types and features, Go log exporter path, Kotlin extension artifact, C# AddSource, Node ESM hook). Onboarding points at the public @maple-dev/effect-sdk and the maple_pk_ ingest key. The internal telemetry-conventions skill gets current paths, cache keys, ingest rejection status rules and MV columns. The dashboard widgets skill is regenerated from dashboard-schema-doc.ts, which had drifted from the committed file.

maple-review-bot · 2026-09-25T17:33:32Z

Maple review

Confidence 5/5 · safe to merge
The only non-doc file changes punctuation inside agent-facing strings, and the committed skill matches what the generator emits.
_{quality 100/100 · no findings · tests not needed · risk low}

A prose pass over docs/ and the Maple skills, plus punctuation-only edits to the dashboard schema doc and its generator. Nothing behavioral changes and it is safe to merge.

renderDashboardSchemaSection strings lose em dashes for commas and colons
- replaces — as the empty cell marker in the panel table
generate-dashboard-skill.ts INTRO now points at apps/ai/src/mcp/lib/dashboard-schema-doc.ts

What was checked

skills/maple-dashboard-widgets/SKILL.md at the head matches the generator's INTRO and body (generated lines 32-33, SKILL.md lines 10-11)
mcp:docs --check compares the committed skill byte-for-byte (generate-dashboard-skill.ts:69-76)
The drift tests read SKILL.md off disk and assert no retired identifiers in it (dashboard-docs-drift.test.ts:67, :85)

_{fee1dfe · Updated on every push. Reply "won't fix" to dismiss a finding, or mention @maple to ask about one.}

coderabbitai · 2026-09-25T17:33:55Z

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 3e901c84-6f2b-41e7-b225-be050a433984

📥 Commits

Reviewing files that changed from the base of the PR and between a8fb51a and fee1dfe.

📒 Files selected for processing (78)

.agents/skills/maple-telemetry-conventions/SKILL.md
.agents/skills/maple-telemetry-conventions/rules/language-bindings.md
.agents/skills/maple-telemetry-conventions/rules/loop-prevention.md
.agents/skills/maple-telemetry-conventions/rules/mv-first-class-columns.md
.agents/skills/maple-telemetry-conventions/rules/resource-attributes.md
.agents/skills/maple-telemetry-conventions/rules/service-map-attribution.md
.agents/skills/maple-telemetry-conventions/rules/span-attributes.md
.agents/skills/maple-telemetry-conventions/rules/status-and-kind.md
apps/ai/scripts/generate-dashboard-skill.ts
apps/ai/src/mcp/lib/dashboard-schema-doc.ts
docs/api-cpu-investigation-2026-09-12.md
docs/api-v1-retirement-audit.md
docs/api-v2.md
docs/attributes.md
docs/backup-and-recovery.md
docs/browser-sdk.md
docs/ci-performance.md
docs/database-query-observability.md
docs/docker-container-monitoring.md
docs/drizzle-v1-effect-upgrade-plan.md
docs/electric-sync.md
docs/error-issue-lifecycle.md
docs/eu-region-plan.md
docs/eventing-extension-guide.md
docs/geo-ai-search.md
docs/github-app-setup.md
docs/http-api-migration.md
docs/infra.md
docs/ingest-wal-durability.md
docs/legacy-cleanup-sweep-2026-09-05.md
docs/local-event-consumers.md
docs/local-mode.md
docs/local-telemetry-archives.md
docs/mcp-oauth.md
docs/openrouter-tracing.md
docs/otel-coverage-roadmap.md
docs/otel-spec/README.md
docs/otel-spec/context-propagation.md
docs/otel-spec/emerging-and-compat.md
docs/otel-spec/logs.md
docs/otel-spec/metrics.md
docs/otel-spec/otlp.md
docs/otel-spec/resource-and-config.md
docs/otel-spec/semantic-conventions.md
docs/otel-spec/stability-and-compliance.md
docs/otel-spec/traces.md
docs/persistence.md
docs/pr-review-agent-plan.md
docs/product-events-dashboard-parity.md
docs/product-events-funnels.md
docs/profiling.md
docs/query-benchmarking.md
docs/query-optimization-implementation-2026-09-05.md
docs/query-optimization-review-2026-09-05.md
docs/query-optimization-second-scan-2026-09-05.md
docs/sampling-throughput.md
docs/self-hosted-clickhouse.md
docs/service-map-architecture.md
docs/service-map-infrastructure.md
docs/signal-to-event-projection.md
docs/sst-fork-workflow.md
docs/tinybird-pr-branches.md
docs/warehouse-rollups.md
skills/maple-audit/SKILL.md
skills/maple-audit/checks.md
skills/maple-csharp-style/SKILL.md
skills/maple-dashboard-widgets/SKILL.md
skills/maple-effect-style/SKILL.md
skills/maple-go-style/SKILL.md
skills/maple-java-style/SKILL.md
skills/maple-kotlin-style/SKILL.md
skills/maple-nextjs-style/SKILL.md
skills/maple-nodejs-style/SKILL.md
skills/maple-onboard/SKILL.md
skills/maple-onboarding-style/SKILL.md
skills/maple-otel-spec-review/SKILL.md
skills/maple-python-style/SKILL.md
skills/maple-rust-style/SKILL.md

 ____________________________________________
< This is what it sounds like when bugs cry. >
 --------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

📝 Generate docstrings

Commit to this branch
Create a new PR

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

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

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

#1064 landed after #1062 renamed @effect-agent/* to effect-agent, so review-failure.ts still imported the retired @effect-agent/core path and broke typecheck and the apps/ai test lane on main.

maple-review-bot · 2026-09-25T17:45:44Z

Note

A newer push replaced 2d20dcf before its review finished. The latest commit is reviewed in a new comment.

maple-review-bot · 2026-09-25T17:46:02Z

Maple review

Confidence 5/5 · safe to merge
The three reviewed files only rename a package import to the name apps/ai/package.json:29 already resolves, and the test moves with it.
_{quality 100/100 · no findings · tests not needed · risk low}

A docs-accuracy pass over docs/ and the Maple skills, plus a one-line import fix: review-failure.ts and its test now import the agent error types from effect-agent/agent-error, the package the workspace actually depends on. Safe to merge.

review-failure.ts imports agent errors from effect-agent/agent-error instead of the retired @effect-agent/core/AgentError
review-failure.test.ts imports from the same module
CLAUDE.md names the package effect-agent

What was checked

effect-agent: 0.1.0-beta.142 is the dependency in apps/ai/package.json:29 and bun.lock:2904, matching the new specifier
Every other import in apps/ai/src/chat/* uses the same effect-agent/<kebab-module> form (effect-agent/agent, agent-policy, run-event)
The renames carry no logic change; the instanceof and .make() usages of the imported errors are untouched

_{94c54cd · Updated on every push. Reply "won't fix" to dismiss a finding, or mention @maple to ask about one.}

Makisuo added 2 commits September 25, 2026 19:22

Makisuo mentioned this pull request Sep 25, 2026

docs(landing): correct service map edges and stale claims on the OTel conventions page #1066

Merged

fix(ai): import agent errors from effect-agent/agent-error

2d20dcf

#1064 landed after #1062 renamed @effect-agent/* to effect-agent, so review-failure.ts still imported the retired @effect-agent/core path and broke typecheck and the apps/ai test lane on main.

docs: name the renamed effect-agent package in CLAUDE.md

94c54cd

Makisuo merged commit ed661ac into main Sep 25, 2026
38 checks passed

Makisuo deleted the chore/docs-accuracy-pass branch September 25, 2026 17:54

Navigation Menu

Repository navigation

docs: fix stale references and wrong instructions in docs and skills - #1065

docs: fix stale references and wrong instructions in docs and skills#1065
Makisuo merged 4 commits into
mainfrom
chore/docs-accuracy-pass

Makisuo commented Sep 25, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

maple-review-bot Bot commented Sep 25, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 25, 2026

Uh oh!

maple-review-bot Bot commented Sep 25, 2026 •

edited

Loading

Uh oh!

maple-review-bot Bot commented Sep 25, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

Makisuo commented Sep 25, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docs (53 files)

Skills

Verification

Follow-ups not in this PR

Summary by CodeRabbit

Uh oh!

maple-review-bot Bot commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Maple review

Uh oh!

coderabbitai Bot commented Sep 25, 2026

Uh oh!

maple-review-bot Bot commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maple-review-bot Bot commented Sep 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Maple review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Makisuo commented Sep 25, 2026 •

edited by coderabbitai Bot

Loading

maple-review-bot Bot commented Sep 25, 2026 •

edited

Loading

maple-review-bot Bot commented Sep 25, 2026 •

edited

Loading

maple-review-bot Bot commented Sep 25, 2026 •

edited

Loading