## Summary
- remove the retired top-level `docs/` Next app and the disabled
docs-sync workflow/script
- add `docs -> showcase/shell-docs` as a top-level symlink for `cd docs`
muscle memory without restoring the old docs tree
- move the docs model allowlist into `showcase/shell-docs/` and retarget
docs validation/doctest extraction to shell-docs content
- update docs/agent guidance and CI path filters so `docs/` is treated
as an alias, not an active separate docs surface
- tighten the pre-commit package check so non-package docs/tooling
changes do not fan out into the full package matrix
## Validation
- `pnpm exec tsx scripts/validate-doc-model-names.ts`
- `pnpm exec tsx scripts/doc-tests/extract.ts`
- `pnpm exec vitest run
scripts/__tests__/validate-doc-model-names.test.ts
scripts/doc-tests/__tests__/extract.test.ts
showcase/harness/src/cli/eval/scope.test.ts`
- `pnpm exec oxlint showcase/harness/src/cli/eval/scope.test.ts
scripts/doc-tests/extract.ts`
- `git diff --cached --check` before follow-up commit
- `test "$(readlink docs)" = "showcase/shell-docs"`
- `test -f docs/package.json`
- `pnpm exec oxfmt --check .claude/docs/documentation.md
.claude/docs/hooks.md AGENTS.md CLAUDE.md CONTRIBUTING.md
showcase/shell-docs/README.md`
- commit hooks passed
## Notes
- historical docs remain recoverable from
`archive/docs-save-do-not-prune` and `archive/docs-retired-2026-06-17`
- I intentionally left Vercel/project teardown out of this PR; this is
repo cleanup only
## What
Updates the v2 `useRenderToolCall` reference page and makes opting a
tool out of the default rendering a single, schema-free call.
## Why
The reference page had drifted out of sync with the hook implementation
(`packages/react-core/src/v2/hooks/use-render-tool-call.tsx`) — most
notably `toolCallId` in the render props, added after the doc was last
touched. While documenting how to opt out of rendering, the natural
example (`useRenderTool({ name: "...", render: () => <></> })`) only
type-checked for the wildcard `"*"`; a named tool required a
`parameters` schema, forcing a throwaway `z.any()`. This PR re-aligns
the doc and removes that rough edge.
## Changes
### Docs (`showcase/shell-docs`)
- `useRenderToolCall.mdx`:
- Document `toolCallId` in the render-prop shape (previously
undocumented).
- Describe agentId-scoped lookup priority: agent-specific → unscoped →
wildcard `"*"` → built-in `DefaultToolCallRenderer`.
- Note args are parsed with `partialJSONParse` (streaming), not strict
`JSON.parse`.
- Correct `toolCall` prop to `toolCall.function.name` /
`toolCall.function.arguments`.
- Rewrite the Status Resolution table to match real logic (`toolMessage`
presence + provider executing set).
- New **"Disable default tool rendering"** section, ordered least→most
specific: wildcard first (all tools), then a **"For specific tools"**
subsection. Both use a schema-free `useRenderTool` call; dropped the old
`useFrontendTool` handler/schema boilerplate.
- `useRenderTool.mdx`: document the render-only (no-schema) named
overload.
### react-core
- Make `parameters` optional on the named `useRenderTool` overload,
mirroring the existing wildcard path; `defineToolCallRenderer` defaults
the args schema to `z.any()` when none is given.
- This lets `useRenderTool({ name: "myTool", render: () => <></> }, [])`
type-check with no Zod schema. Typed `parameters` behavior is unchanged.
- Added a test for the named render-only registration.
## Verification
- `@copilotkit/react-core` tests pass (1280) including the new case;
`build` (tsc) passes.
- Opt-out snippets type-checked in-package (`tsc`): wildcard,
specific-name (no schema), and named-with-schema all compile.
- `oxlint` (shell-docs) passes — 0 errors.
- Previewed locally at `/reference/hooks/useRenderToolCall`.
Resolve event-renderer.ts onRunFinishedEvent: keep the native turn stream open
(finalized in finish()) AND retain the legacy per-message stream drain from main
(#5573) as a no-op-in-native safety net. app/index.ts (telegram adapter from
#5520 + showToolStatus:false) and create-bot.test.ts auto-merged.
Under the pinned-prod contract, prod is intentionally digest-pinned behind
:latest. image-drift now renders such prod services green (pinnedExpected)
instead of red; a genuinely missing digest stays red. Staging unchanged.
Prod services are now born pinned to a resolved @sha256 digest (mirroring
the Ruby promote CLI's GHCR resolver) instead of the mutable :latest tag,
fail-loud on resolve failure, and goLive asserts the prod source.image is
digest-pinned. Adds DI-testable assertProdDigestPinned + coverage.
Approach (A) reorder: decode -> html-strip -> headTailCap -> scrub(head)+scrub(tail).
The prior order scrubbed the FULL decoded body before the cap, so a body >32KB hit
scrubSecrets' bounded-prefix path: it truncated to a ...[unscanned:N] prefix BEFORE
headTailCap, which (1) lost the real tail, (2) never scanned the real tail for secrets,
and (3) zeroed elided_count. Reordering scrubs each retained <=16KB segment AFTER the
cap: input is bounded per-segment (linear regex x bounded length = ReDoS-impossible, no
scan-budget truncation), the captured head AND tail are the REAL ends of the body, and
elided_count comes from headTailCap on the FULL body. The unrelated 2KB metadata-hot-path
scan guard (SCRUB_MAX_SCAN_LEN) is untouched; the now-unneeded RAW_BYTE_SCAN_MAX export
is removed.
The emit-hardening redesign added a 2KB SCRUB_MAX_SCAN_LEN guard inside
scrubSecrets, correct for the DEFAULT-tier metadata hot path (legit values
<=512B). But raw-byte-capture.ts also calls scrubSecrets on the DECODED wire
body, which is legitimately large (<=16KB head + <=16KB tail = up to 32KB).
The 2KB guard truncated the body to ~2KB before headTailCap ran, so for an
>32KB body elided_count became 0 and the head+tail elision never triggered.
Approach: parameterize the scan cap (chosen over the reorder-and-scrub-segments
alternative because it is a minimal, local change that preserves the documented
decode->scrub->html-strip->headtail pipeline order and keeps the metadata
default behavior byte-identical for all existing callers).
- scrub.ts: scrubSecrets gains an optional maxScanLen param defaulting to the
exported SCRUB_MAX_SCAN_LEN (2KB). Metadata/validateMetadata callers are
unchanged; the ReDoS guard on the hot path is untouched.
- raw-byte-capture.ts: passes RAW_BYTE_SCAN_MAX (head+tail cap = 32KB) so the
full retained sample is scanned (no secret in the kept head/tail escapes) and
headTailCap sees the un-truncated body. The three scrub regexes are linear at
any bounded length, so the larger bound stays ReDoS-safe.
- scrub.test.ts: asserts the default param still applies the 2KB guard AND an
explicit larger cap does not truncate, proving both contexts.
The redesigned scrub regexes are linear, but the previous hard <50ms bound
flaked under JIT warm-up and shared-runner load (observed 77ms on a loaded
machine). Add a timeScrub helper that discards a warm-up call before timing
and assert against a 500ms ReDoS ceiling — wide enough to be jitter-immune,
still ~3x under the legacy ~1.4s catastrophic-backtracking blowup it guards
against.
CR-round hardening that builds on the bug #1/#2 fixes: the P2 in-flight race
guard now reads the running digest from meta.imageDigest (the dead guard
never REFUSEd before) and is skipped on the --digest override path. Refresh
the snapshot ivar-lint allowlist line numbers after the surrounding CR line
drift.
Bug #2: promote used serviceInstanceRedeploy, which replays the EXISTING
deployment and never pulls the newly-pinned digest, so prod could keep
serving stale. Switch to serviceInstanceDeployV2 to spawn a NEW deployment
that pulls the pinned digest, then verify_serving_digest! fail-loud asserts
the new deployment reaches SUCCESS and its meta.imageDigest == the pinned
digest. Update the promote mock-GraphQL fixtures across the spec suite to
return serviceInstanceDeployV2 + meta.imageDigest accordingly.
Bug #1: resolved_prod_image re-resolved :latest at promote time, so prod
could be pinned to a digest different from what staging is actually serving.
Now resolve via staging_running_digest (latestDeployment meta.imageDigest)
and REFUSE when unavailable. Add detect_staging_drift +
emit_staging_drift_warnings to surface (non-fatally) when :latest has moved
past staging's running digest; aggregate markers across the fleet in
promote-fleet.sh (printf join) and plumb the drift_line through
showcase_promote.yml (both Slack payloads + fallback log + GITHUB_OUTPUT
single-line guard). Skip drift detection on the --digest override path.
Adds a **Vue** section to the reference docs at `/reference/vue`,
alongside the existing React, React Native, and Core references. Until
now there was no Vue reference, so users and agents had no way to
discover the API.
It mirrors the React v2 reference but documents the real
`@copilotkit/vue/v2` API, with Vue idioms throughout (composables return
refs, slots instead of render props, kebab-case props, Vue SFC
examples).
### What's included
- The Vue index page (install, styling, provider setup)
- 14 composables (useAgent, useFrontendTool, useHumanInTheLoop,
useThreads, and the rest)
- 9 components (CopilotKitProvider, CopilotChat, CopilotPopup,
CopilotSidebar, and the chat sub-components)
- Vue registered in the SDK picker and the reference landing page
### Screenshots
Landing page (SDK picker set to Vue, full sidebar):
A composable page (useAgent):
A component page (CopilotKitProvider):
### How it was verified
- All 24 pages render (HTTP 200) on the local docs server
- Content shows up in `llms.txt` and `llms-full.txt`
- Each page was written from the Vue source, not copied from React, and
spot-checked for accuracy
Guide content and new demos are out of scope.
applyByteCap's "hard guarantee" docstring was false: it trimmed only the
metadata bag (Steps 1-3), so caller-supplied variable-length STRING fields
that the caller controls — `slug`, `demo`, `parent_span_id`, `trace_id` —
were never trimmed. A 5000-char `demo`/`slug` enqueued ~5552B over the 2048B
default cap while stamped `_truncated:true` as if bounded (spec §7 R5-F3
violation).
Add Step 4: after the metadata bag is exhausted (dropped to {}), if the
envelope is STILL over cap the excess can only be in those four caller string
fields. Clamp them longest-first to a short prefix + `…[clamped]` marker until
under cap. Minted ids (`test_id`, `span_id`) are left intact — they are
fixed-width by construction and already bounded; `trace_id` mirrors `test_id`
(fixed-width UUIDv7) so it is included only for completeness so the
post-condition holds even for a hand-built oversized `trace_id`. Format-
constrained / enum / numeric fields (`boundary`, `layer`, `outcome`, `ts`,
`mono_ns`, `duration_ms`, `schema_version`, 9-key `edge_headers`) are bounded
by construction and never touched. Post-condition: serializedSize(env) <= cap
for ANY realistic envelope.
Fix `_truncated` semantics: stamp it only when trimming ACTUALLY occurred (a
field was modified), per its documented meaning, rather than on bare over-cap
detection. A detection that finds nothing trimmable until Step 4 ends with
Step 4 trimming and stamping.
applyByteCap is private; its sole caller is buildEnvelope (which both emit()
and flush() route through). Pure instrumentation preserved — never throws.
Adds a durable bytecap-invariant matrix test over pathological shapes (huge
slug/demo/parent_span_id, huge nested + scalar-heavy metadata, default + debug
tiers) asserting serializedSize(env) <= BYTE_CAP_BY_TIER[tier] for every case.
The §6 PII guarantee was incomplete in three ways that three CR rounds kept
re-finding in the same class. This completes the scrub.
1. Nested-value scrub. `validateMetadata` scrubbed ONLY top-level string
values; secrets buried in allow-listed array/object values (e.g.
`backend.error.caught.stack_brief`, `aimock.match.decision.reject_reasons`)
leaked. New `scrubDeep(value)` in scrub.ts (leaf module; called from
schema.ts which already imports from ./scrub.js — no cycle) applies
`scrubSecrets` to every string LEAF at any depth, preserving structure and
non-string leaves. validateMetadata deep-scrubs object/array values on a
`structuredClone` (cycle-preserving; no caller mutation), falling back to
in-place scrub on the rare unclonable input (correctness > no-mutation).
Walker cycle-safety: ITERATIVE (explicit work stack, never the call stack)
with a WeakSet visited-guard — a self-referential/cyclic or 10k-deep object
is visited once and never re-entered, so no stack-overflow/hang on untrusted
metadata. Only plain objects (Object.prototype/null proto) and arrays are
descended; Date/RegExp/etc. are left as-is.
2. base64url key alphabet. SK_KEY_REGEX
`/sk-(?:[A-Za-z0-9_-]*[A-Za-z0-9]{12,})[A-Za-z0-9_-]*/g` redacts modern keys
whose body uses base64url incl. `_`/`-` (sk-ant-api03-AbCd_Ef-…, sk-proj-…),
with a ≥12-char contiguous-alnum entropy gate (shortest real tail
`0123456789xyzAB` = 15) so prose ("ask-me-later" → me/later; "task_list_items"
uses `sk_` not `sk-`) is NOT redacted. Legacy `sk-<16+ alnum>` still matches.
3. multi-@ URL userinfo. URL_USERINFO_REGEX `/([a-z][a-z0-9+.-]*:\/\/)[^/\s]*@/gi`
redacts the FULL authority up to the LAST `@` before the host/path; excluding
`/` keeps it from crossing into the path. Fixes `https://a@b@c.com/x` leaking
`b@c.com`; user:pass@ and bare-token tok@ still work.
scrubSecrets signature + SCRUB_REPLACEMENT unchanged. Call sites of the deep
scrub: schema.ts `validateMetadata` (object/array branch) → scrubDeep; emit.ts
buildEnvelope routes data-plane metadata through validateMetadata unchanged.
Red→green: scrub-coverage corpus (schema.test.ts) + nested array-of-objects
sweep & cyclic-input safety (emit.test.ts) observed RED (base64url key
unredacted; multi-@ tail leaked; nested secret survived envelope JSON), GREEN
after fix. Full cvdiag suite 119/119 (pb-writer live-PB test skipped sans
PB_BIN). tsc clean; oxfmt + oxlint 0 errors on touched files.
buildEnvelope's accounting branch aliased args.metadata into the
envelope; applyByteCap's in-place trims (Steps 1/2) then mutated the
caller's object as a side effect of pure instrumentation. Shallow-clone
the accounting bag before it enters the envelope (data-plane events
already get a fresh `survivor` from validateMetadata, so only the
accounting branch needed the clone).
applyByteCap Step 3's full-bag size-drop stamped _metadata_dropped, but
that flag is the §6 PII closed-world signal (set by buildEnvelope when
validateMetadata drops unknown keys); overloading it for a SIZE drop
pollutes PB drift queries. A size-drop is already observable via the
_truncated flag stamped earlier, so Step 3 now drops the bag without
touching _metadata_dropped. The genuine PII stamp is unchanged.
Call sites (both private, in-module only):
buildEnvelope: emit() (emit.ts:309), flush() accounting (emit.ts:514).
applyByteCap: buildEnvelope() (emit.ts:388).
No external callers.
The old SK_KEY_REGEX /sk-[A-Za-z0-9]{16,}/ stopped its character class at
the first hyphen, so modern hyphenated-prefix keys leaked into PocketBase:
the `proj` (4) / `ant` (3) / `api03` (5) prefix segments never reached the
required 16-char run, so `sk-proj-…` and `sk-ant-api03-…` never matched and
were stored verbatim — defeating the §6 secret-scrub guarantee for the two
most common real-world key formats.
New pattern: /sk-(?:[A-Za-z0-9]+-)*[A-Za-z0-9]{16,}/g
`sk-` then zero-or-more hyphen-terminated alnum SEGMENTS (the prefix words)
followed by a ≥16-char alnum entropy TAIL.
Why it does not over-redact ordinary hyphenated prose: the mandatory 16+
alphanumeric tail is the entropy gate. Words like "ask-me-later" or
"task-list" have no 16+ contiguous alnum run after an `sk-`, so they never
match (negative test asserts the phrase is returned unchanged). The legacy
`sk-<16+ alnum>` form is preserved as the zero-segment case.
SCRUB_REPLACEMENT and scrubSecrets structure unchanged. Four new tests
(sk-proj-, sk-ant-api03-, legacy sk-<16+>, negative over-redaction);
RED on the two hyphenated cases pre-fix, GREEN after. Full cvdiag suite
110/110.
Move the `pbWriter === undefined` early-return to the TOP of flush(), before
the queue.splice and the drop-accounting block. Previously, with no writer,
flush() spliced the queue into `batch` and discarded it on the trailing
early-return while resetting droppedSinceFlush to 0 — silently losing all
queued telemetry every flush window. Under { autoFlush: true } with no writer
this was continuous data loss, contradicting the documented pbWriter contract
("When absent, events stay queued").
flush() callers: the startBackgroundFlush() interval timer and any manual
flush() call. With a writer present, the A3 drop-accounting + reset-only-
after-landing behavior is unchanged.
flush() previously zeroed droppedSinceFlush BEFORE confirming the accounting
emit() landed, then recovered the just-enqueued event via a fragile second
splice of the whole queue (which APPENDS despite the "prepend" docstring). If
that emit() returned null (validateEnvelope failure / exception) the drop count
AND the cvdiag.queue_dropped record were permanently lost.
Fix: extract the envelope-construction + validateEnvelope + applyByteCap logic
of emit() into a private buildEnvelope() helper (no enqueue side effect). flush()
now calls buildEnvelope() for the accounting event and pushes the result DIRECTLY
into the outgoing batch (no queue round-trip / re-splice). droppedSinceFlush is
reset to 0 ONLY after the accounting envelope is in the batch, so a null/throw
retains the count for the next flush. Docstring updated to "append" (event order
in a best-effort batch is not load-bearing — the classifier re-sorts by mono_ns/ts).
Call sites of the extracted buildEnvelope(): emit() (enqueues result, still
resolves/returns CvdiagEnvelope|null) and flush() (appends to batch, still
resolves/never-rejects). Public method signatures unchanged.
Red-green: src/cvdiag/emit.test.ts. Loss-path test forces the accounting build
to return null and asserts the drop count is retained (lands on the next flush);
RED on original = 0 queue_dropped events land (count silently lost), GREEN after
fix = exactly 1 lands with _dropped_count preserved.
applyByteCap previously stamped _truncated:true and trimmed only >64-char
string values / nested objects in metadata. An envelope over the tier byte
cap due to many short-string or numeric/boolean metadata values (none
reachable by that pass) was stamped truncated yet still enqueued OVER cap,
violating spec §7 R5-F3 ("the whole serialized envelope must fit the tier
byte cap").
Fix escalates while still over cap: (1) legacy >64-char/object trim, then
(2) clamp ALL string values progressively, then (3) drop metadata to {}
(stamping _metadata_dropped). Fixed scalar envelope fields are bounded by
construction, so an empty metadata bag is the hard guarantee the enqueued
row fits any realistic cap. Method stays pure-instrumentation: it never
throws.
Call sites: applyByteCap is private; emit() (emit.ts:361) is the sole caller
and already wraps it in try/catch. Post-condition holds: on return the
serialized envelope is <= cap OR metadata is already {}.
validateMetadata kept surviving metadata VALUES verbatim and never scrubbed
them, so Bearer/sk-/URL-userinfo secrets in free-text fields (e.g.
*.message_scrubbed, probe.*.url) reached PocketBase unscrubbed — violating
spec §6 (the field is literally named message_scrubbed). Now every SURVIVING
string metadata value is run through scrubSecrets; non-string values are left
untouched.
Also tighten URL_USERINFO_REGEX: the old pattern required a user:password@
colon, so a bare-token userinfo (scheme://token@, e.g. https://ghp_xxx@host)
was NOT redacted. The new pattern matches any non-/, non-@, non-ws run before
@, covering BOTH the colon and no-colon forms; the $1[REDACTED]@ replacement
shape is unchanged and the / exclusion confines the match to the authority.
Import-cycle avoidance (approach a): moved scrubSecrets + its regex constants
into a new leaf module scrub.ts that has NO intra-cvdiag imports. Applying the
scrub inside validateMetadata required schema.ts to call scrubSecrets, but
edge-headers.ts already imports EDGE_HEADER_KEYS from schema.ts, so importing
scrubSecrets from edge-headers into schema would form a schema -> edge-headers
-> schema cycle. The leaf module is imported by both; edge-headers re-exports
the symbols so the historical public surface is preserved.
scrubSecrets call-site enumeration (all still resolve):
- src/probes/drivers/d4-chat-roundtrip.ts (imports from ./cvdiag/index.js;
index.ts does `export * from ./edge-headers.js`, which re-exports scrub.ts)
- src/cvdiag/raw-byte-capture.ts (imports from ./edge-headers.js — re-export)
- src/cvdiag/index.ts (`export *` from edge-headers — re-export intact)
Sam Julien
