You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit fd4323a
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: apps/docs/COPY_AUDIT.md
+39-3Lines changed: 39 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,9 @@
2
2
3
3
Audited from staging snapshot `4d2fa26f5de0532048487a94bbe1afc744500dfe`, beginning 2026-10-13. Rebased onto `origin/staging` at `9058427155` and reviewed the 20 intervening commits before final validation. The [editorial guide](EDITORIAL_GUIDE.md) defines the final voice, terminology, organization, media, and generated-source rules.
4
4
5
-
## Scope and method
5
+
## Original copy pass: scope and method
6
6
7
-
The inventory contains **484 entries**: 153 authored MDX pages, 28 generated CLI references, and 303 generated API operations. One authored entry is the root redirect, leaving 483 readable routes. All 306 integration pages are excluded from copy changes, but their links and shared component/asset dependencies are checked.
7
+
The inventory contains **484 entries**: 153 authored MDX pages, 28 generated CLI references, and 303 generated API operations. One authored entry is the root redirect, leaving 483 readable routes. That original pass excluded 306 integration pages from copy changes while checking their links and shared dependencies. The later complete integration review is recorded in [INTEGRATIONS_AUDIT.md](INTEGRATIONS_AUDIT.md).
8
8
9
9
Each section received a complete audit before rewriting. Reviewers read the entire assigned copy, retained a per-page ledger, compared consequential claims with the owning implementation, checked examples and limits, inspected local media, and used current primary documentation for external setup. Repeated generated schema prose was read once per unique value while retaining every operation-to-field relationship. This is a documentation accuracy review, not proof of a live hosted configuration or an exhaustive security review.
10
10
@@ -14,7 +14,7 @@ Useful facts are retained or moved to a linked canonical owner. Changes remove r
14
14
15
15
The original copy often contained useful technical detail, but placed it behind repeated benefits, broad promises, FAQs, and screenshots of ordinary controls. Pages mixed concepts, setup, reference, and troubleshooting in different orders. The final standard uses a short task-focused opening, sentence-case headings, exact visible labels, and a consistent order for each page type. It preserves detailed references where brevity would hide a requirement or failure consequence.
16
16
17
-
## Coverage
17
+
## Original copy pass: coverage
18
18
19
19
| Section | Entries | Disposition |
20
20
| --- | ---: | --- |
@@ -72,6 +72,42 @@ The final source pass also reviewed the later Chat content-delivery gate, crawle
72
72
73
73
## Components and asset cleanup
74
74
75
+
### October 20 visual refinement
76
+
77
+
Current source inventory after staging sync: 490 MDX files, including 308 integration pages, and 33 article image uses. Counts in the dated follow-ups below describe the checks at that stage. The final font review removed the article and footer Season overrides: body copy and navigation retain the existing Inter family, while existing shared controls retain their established typography.
78
+
79
+
#### Final pre-ship review
80
+
81
+
- Removed the partial font-family change, verified the Browser settings bottom-edge crop, and checked that all 33 image uses match their overview/detail purpose. Removed two WebP substitutions that were larger than their originals; the media viewer retains source PNGs for zoom fidelity.
82
+
- Rebased the documentation work onto current staging without unrelated release commits. Reviewed the newly added Help Scout reference, removed its repeated capability list and closing promotion, and retained authentication, webhook-signature, connector, and field details. Its action and trigger tables use the shared disclosures.
83
+
- Current-source typography checks pass at 320, 390, 768, and 1280px across Desktop, Editor, and Help Scout, with matching article/navigation font families and no document overflow. The hydrated shared media viewer preserves its background at 125% zoom, closes with Escape or image activation, and restores focus to its trigger; desktop and phone layouts were inspected in a focused component preview.
84
+
- React cleanup found no additional effect/state/query issues. API request panels stay mounted to avoid repeating syntax highlighting when switching languages; disclosure controls have 44px touch targets. Full repository validation remains assigned to CI.
85
+
86
+
#### Markdown examples follow-up
87
+
88
+
- Replaced the Files overview with a current Sim Desktop capture of Chat reviewing a Markdown release brief, including a real checklist, owner table, and JSON block. Added focused table-toolbar and code-control captures to the editor guide. The overview retains the bottom-edge crop; control details use the shared inset frame and architecture background. The Chat files guide keeps its simpler release-notes example.
89
+
- Created a small fictional document through Chat and inspected the actual rendered output. Shortened its sample names and metadata before capture. No UI was fabricated, no file was publicly shared, and no integration or deployment settings changed.
90
+
- Read both complete pages, kept their limits and access rules, and made the editor introduction include Chat. Verified the table's fixed header and disabled column resizing in the editor configuration, keyboard access to the table toolbar, and the JSON language control. Added the existing line-wrap and copy controls to the code-block instructions.
91
+
- Both affected MDX pages compile. All 33 article image uses across 489 MDX source files resolve with matching dimensions. All 18 local links from these pages resolve, including the generated bulk-download API page verified in the browser. Files and Editor passed 44 page/theme/viewport checks at 320, 390, 639, 640, 767, 768, 1023, 1024, 1279, 1280, and 1536px, with no document overflow, unloaded images, or image distortion. Desktop and phone compositions were visually inspected.
92
+
- Verification used the lightweight current-source preview. The final production build, full type checks, audits, and test suites remain deferred to CI; no heavy local checks were run.
93
+
94
+
#### Chat context follow-up
95
+
96
+
- Replaced standalone Files, Tables, and first-run overview captures with genuine Sim Desktop views that keep the conversation beside the resource. Files and workflow captures were taken again; Tables reuses the approved introduction's Chat/table composition. The grayscale scenery and bottom-edge crop remain intact. The file editor, connection picker, settings, and provider setup images retain focused views where their controls explain the task.
97
+
- Applied the captures to Files, Tables, Getting started, Sim Desktop, and the Chat file/workflow guides. Getting started now leads with a concise Chat request and retains the complete manual builder procedure, model prerequisites, sample output, and failure recovery. Resource overviews link to their corresponding Chat guide.
98
+
- Read the complete affected pages and shortened repetitive prompt lists across Chat's files, workflows, tables, knowledge, actions, and research guides. Kept permissions, content-withholding behavior, write-versus-result distinctions, scheduling/deployment semantics, limits, syntax, and recovery instructions. Removed a dated model-swap example without replacing it with an unverified model recommendation.
99
+
- Verified the composer's **+** resource picker in Sim Desktop: selecting the example file adds its reference and opens the file beside Chat. The source's `handleContextAdd` and `resolveResourceFromContext` agree. Cleared the temporary composer reference without sending it or modifying the file. The workflow capture displays an existing successful execution; no workflow was deployed or rerun for this follow-up.
100
+
- Lightweight checks: all 11 affected MDX pages compile; all 31 image uses across 489 source MDX files resolve with matching intrinsic dimensions; the docs manifest and `git diff --check` pass. Current-source previews use the actual shared components and prose styles. Browser checks cover 81 page/viewport combinations, including 320, 390, both sides of 640/768/1024/1280, and 1536px, with no document overflow or image distortion. Below-fold lazy images were checked after scrolling them into view. Light and dark captures were inspected.
101
+
- This follow-up did not run a full local build or repository-wide tests, per request. The current-source preview is static and does not hydrate the media viewer; the existing production preview predates these final copy changes. Final production compilation and full test suites remain for CI.
102
+
103
+
The initial visual pass covered 489 MDX files, including integration references and the root redirect. Its 29 article screenshots used the shared branded `Image` treatment. Overview and result captures extend to the frame's bottom edge; focused controls and complete dialogs retain their inset. Current desktop captures now cover Chat, Getting started, Tables, Files, the editor toolbar, the connection picker, integrations, browser settings, and run logs. Retained provider and enterprise screenshots use optimized assets with verified intrinsic dimensions.
104
+
105
+
The remaining navigation cards on Workflows, Deployment, and Self-hosting became concise links or comparison tables. The Connections video depended on a configured CDN and rendered an empty frame in the local build; a current reference-picker capture replaces it. Its unused video component and URL helper were removed. The 39 interactive workflow examples remain where they explain execution or data flow.
106
+
107
+
Verification for this final pass: 56 affected MDX files compile; all 29 screenshot dimensions and source assets resolve; generated integration docs and the docs manifest are current; scoped formatting and diff checks pass. Browser checks cover eight representative updated pages at actual 320, 390, 768, and 1280-pixel widths, plus expanded reference tables, keyboard activation, and direct heading links. Current-source previews use the real MDX components and page tokens without a full Next build or client hydration. Full builds, type checks, and the repository test suite are deferred to CI at the user's request; earlier production checks below do not validate these later edits.
108
+
109
+
### Earlier copy pass
110
+
75
111
Shared navigation and API UI labels follow sentence case while preserving acronyms and product names. Authored tabs use a local wrapper around Fumadocs selection and keyboard behavior: mixed panels keep their inset, single code fences fill the frame, and mobile tab lists scroll with 44px targets. SSO provider anchors use native explicit triggers with `aria-controls` matching their panel IDs; keyboard navigation, selection, and bookmarked activation remain native. The shared tab frame uses the actual header/TOC row offset when scrolling a bookmarked panel into view. The compact drawer uses 30px visible chip faces within 44px mobile touch targets, aligned full-width dividers, and the shared section order. TOC/header rows reserve their actual heights at mobile/tablet breakpoints; prose wraps without changing intentional code/table scrolling. API method badges use existing platform surface and text tokens instead of custom color overrides. Integration MDX content remains unchanged. The final pass removes the unused ActionMedia component and its local styling, three unused workflow-preview definitions/exports, and 111 local media files (15,187,771 bytes). Every removed asset belonged to an originally reviewed page and had no basename consumer in current repository source, including integrations and application code. Shared components and media with other consumers remain. Remote media was removed from pages only; no remote assets were deleted.
76
112
77
113
FAQ answers were folded into their relevant sections. Callouts decreased from 234 to 117; authored Image/ActionImage and Video/ActionVideo instances decreased from 178 to 23. All 36 editorial placeholders were removed. These counts cover the 153 authored entries and exclude generated reference pages and integrations.
Copy file name to clipboardExpand all lines: apps/docs/EDITORIAL_GUIDE.md
+7Lines changed: 7 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -60,10 +60,15 @@ A link replaces repeated detail only after the owner contains it. Keep a concise
60
60
- Use a callout for a specific prerequisite or a non-obvious security, data-loss, or operational risk that deserves interruption. Use ordinary prose or a table for normal explanation. Keep important limits visible.
61
61
- Use Markdown lists and tables for simple procedures and reference data. Use tabs for distinct configurations and Steps for substantial sequential procedures.
62
62
- Integration table cells use ordinary word wrapping so short field names and types stay readable. Keep long tokens within the existing table scroll container; do not let them widen the page.
63
+
- On large integration references, keep action and trigger descriptions visible and fold their field tables into `ReferenceDetails`. Preserve headings inside each disclosure so direct links and browser search can reveal them. Setup requirements and consequential warnings stay outside the folded tables.
63
64
- Match inline code to Sim Chat: normal-weight monospace text, tight padding, and the existing borderless filled surface tokens. Scope the treatment to prose code; preserve fenced examples, API route bars, schema controls, and selector labels.
64
65
- Use shared `ChipSelect` controls for API response and request-example pickers, with accessible names that include the current value, checked radio semantics for single choices, and menus aligned to their triggers. Keep docs pickers nonmodal so they do not hide lazily hydrating siblings. Keep response headings free of inherited extra margins. Scope dependency filter styling to `data-object-search-input`, including schema popovers portaled to the body; focus stays inside the field, and touch fields retain the shared target and text sizes.
65
66
- Import authored tabs from `@/components/ui/tabs`. Mixed panels retain a content inset; only a single code fence fills the frame. Keep long tab lists horizontally scrollable and long prose references wrapped. For bookmarked panels, use explicit native `TabsList`/`TabsTrigger` controls with `aria-controls` matching each panel ID; changing a panel ID alone leaves the generated control pointing at a nonexistent element.
66
67
- Keep a screenshot when it locates a difficult control or shows a meaningful result. Keep a video when motion explains behavior that text or a static example cannot. Remove decorative, redundant, misleading, or non-rendering media.
68
+
- Capture the current product with a small, neutral example. Use the shared `Image` component: `overview` for a workspace or full settings panel, `detail` for a complete dialog or focused control, and `result` for an output. Keep the branded background in both the page and media viewer. Overview and result images extend to the frame's bottom edge, with scenery above and beside the window. Crop empty canvas at the source; never cut off a control or result needed by the instructions. Keep complete dialogs inset so their actions remain visible.
69
+
- Use a full-width window when the surrounding UI explains where to act. Use a closer crop when the reader needs to identify a specific control. Preserve the actual window chrome, borders, and product colors; do not fabricate UI or add imitation operating-system controls. Check each composition at its rendered article width and in the media viewer.
70
+
- For resource overviews, keep Chat visible with the workflow, table, or file open beside the conversation. Show a real request and result using neutral example data. Reserve standalone views for instructions that require their controls, and retain focused crops for dialogs or field details. Selecting a resource through the composer's `@` picker or **+** menu adds context and opens its panel; verify this behavior when documenting a new resource type.
71
+
- Keep one useful capture per task or result. Prefer concise steps over a screenshot for every click. Use the supplied grayscale landscapes and architecture, preserve the product's actual colors, and add a caption only when it explains something the image or adjacent text does not.
67
72
- Inspect media before describing it as stale. Uninspected remote media is unverified; it may still be removed when the written procedure fully covers its purpose. Do not fabricate replacement captures.
68
73
- Remove imports, components, preview definitions, local styling, and assets made unused by an edit after checking all consumers, including integration pages.
69
74
@@ -85,6 +90,8 @@ Edit generated prose at its owner, then regenerate:
85
90
86
91
Do not hand-edit generated pages, JSON specifications, or marked generated regions. Preserve all argument, option, schema, authentication, and confirmation detail. CLI descriptions also feed command discovery; run the existing search-ranking checks after changing help copy. Validate rendered request examples against their canonical input contracts; schema validity alone may still leave a semantic error such as an invalid serialized workflow.
87
92
93
+
The integration generator refreshes tool metadata before reading it. Its `--check` mode verifies that dependency without writing files and stops if it is stale.
94
+
88
95
Integration `MANUAL-CONTENT` regions are intentionally authored source: the generator reads and preserves them from the existing MDX. Edit generated descriptions in their block, tool, trigger, or OAuth owner. Edit fully authored credential guides registered in `content/integration-navigation.json` directly. Preserve action names, field names, scopes, conditional requirements and nested output paths. Token validation may verify identity without proving resource access, every permission, or future token validity; state what the actual validator checks. Preserve old heading anchors when standardizing shared generated headings. After regeneration, run it again and confirm no further changes; verify registered guides and all authored regions survive.
Copy file name to clipboardExpand all lines: apps/docs/INTEGRATIONS_AUDIT.md
+5-1Lines changed: 5 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,8 @@
1
1
# Integration documentation audit
2
2
3
-
This pass reviews all 306 integration pages: 281 generated references and 25 authored pages (the integration overview, A2A, and registered connection guides). The baseline is staging commit `2676575f218c2080c0cf1e437be9100d320b0134`. [EDITORIAL_GUIDE.md](EDITORIAL_GUIDE.md) defines the ongoing format; [scripts/README.md](../../scripts/README.md) explains regeneration and ownership.
3
+
The original pass reviewed 306 integration pages: 281 generated references and 25 authored pages (the integration overview, A2A, and registered connection guides). The baseline is staging commit `2676575f218c2080c0cf1e437be9100d320b0134`. [EDITORIAL_GUIDE.md](EDITORIAL_GUIDE.md) defines the ongoing format; [scripts/README.md](../../scripts/README.md) explains regeneration and ownership.
4
+
5
+
The current staging sync contains 308 integration pages. The added Help Scout reference received the same disclosure treatment and a copy pass that removed repeated capability lists while retaining connection, trigger, and knowledge-base setup. Authentication and webhook signatures were checked against the owning implementation and [Help Scout authentication](https://developer.helpscout.com/mailbox-api/overview/authentication/) and [webhook documentation](https://developer.helpscout.com/webhooks/). Historical counts below describe the validation at each earlier stage.
4
6
5
7
## Assessment and changes
6
8
@@ -48,6 +50,8 @@ PR review checked the capability boundaries again against each operation. Correc
48
50
49
51
## Validation
50
52
53
+
The October 20 visual pass folds large trigger field tables into the same native `ReferenceDetails` component used by action references. This affects 448 trigger definitions on 50 pages. All trigger descriptions remain visible; normalized content and heading comparisons across all 307 MDX files in this directory found no content loss or heading changes. Regeneration is deterministic, and affected MDX compilation passes. Browser checks cover Notion's mixed action/trigger reference and the IMAP and Twilio trigger-only pages, including narrow layouts, expanded tables, keyboard use, and direct links into disclosures. Full build and test validation for these later refinements remains deferred to CI.
54
+
51
55
Search citation extraction now honors explicit heading IDs without including alias syntax in result titles. Retained parser regressions fail before the fix and when either ID preservation or label cleanup is removed; ordinary heading links remain unchanged.
0 commit comments