Merge pull request #50 from ryanbas21/docs/update-to-current

docs: update documentation to match current codebase

Author: ryanbas21

README.md

@@ -28,6 +28,13 @@ Analyze and enforce tree-shakeability across your packages — catch bundle-bloa
 | [`treeshake-check`](packages/treeshake-check)                 | CLI & library — checks whether a package can be fully tree-shaken by Rollup | [![npm](https://img.shields.io/npm/v/@wolfcola/treeshake-check)](https://www.npmjs.com/package/@wolfcola/treeshake-check)                 |
 | [`eslint-plugin-treeshake`](packages/eslint-plugin-treeshake) | ESLint plugin that flags code patterns known to break tree-shaking          | [![npm](https://img.shields.io/npm/v/@wolfcola/eslint-plugin-treeshake)](https://www.npmjs.com/package/@wolfcola/eslint-plugin-treeshake) |
 
+### Utilities
+
+| Package                                                       | Description                                                   | npm                                                                                                                             |
+| ------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| [`dead-export-finder`](packages/dead-export-finder)           | CLI to find unused exports across monorepo package boundaries | [![npm](https://img.shields.io/npm/v/@wolfcola/dead-export-finder)](https://www.npmjs.com/package/@wolfcola/dead-export-finder) |
+| [`changeset-sync-manifest`](packages/changeset-sync-manifest) | Syncs package version from changesets to manifest files       | private                                                                                                                         |
+
 ---
 
 ## Quick start
@@ -104,10 +111,13 @@ pnpm add @wolfcola/devtools-bridge
 
 ```ts
 import { davinci } from '@forgerock/davinci-client';
-import { attachDevToolsBridge } from '@wolfcola/devtools-bridge';
+import { attachDaVinciBridge } from '@wolfcola/devtools-bridge';
 
 const client = await davinci({ config });
-attachDevToolsBridge(client, config);
+const handle = attachDaVinciBridge(client, config);
+
+// When done:
+handle.detach();
 ```
 
 The bridge is a no-op when the extension is not installed.

apps/docs/README.md

@@ -1 +1,60 @@
-# README
+# @wolfcola/docs-site
+
+The documentation site for wolfcola devtools, built with [elm-pages](https://elm-pages.com/).
+
+## Development
+
+```bash
+pnpm --filter @wolfcola/docs-site dev
+```
+
+Opens a local dev server with hot reload.
+
+## Build
+
+```bash
+pnpm --filter @wolfcola/docs-site build
+```
+
+Generates a static site in `dist/` using the Netlify adapter. The site is served under the `/devtools/` base path.
+
+## Content
+
+Documentation is authored as Markdown files in the `content/` directory:
+
+| Directory               | Section      | Description                                          |
+| ----------------------- | ------------ | ---------------------------------------------------- |
+| `content/docs/`         | Guides       | Getting started, extension usage, integration guides |
+| `content/packages/`     | Packages     | API reference for each published package             |
+| `content/contributing/` | Contributing | Development setup, code style, release process       |
+
+Each Markdown file has YAML frontmatter with `title`, `description`, `section`, and `order` fields used for navigation and search indexing.
+
+## Architecture
+
+- **elm-pages** — static site generator with file-based routing
+- **Elm** — all page logic, layout, search, and theme toggle
+- **Vite** — bundler (configured via `elm-pages.config.mjs`)
+- **Netlify** — deployment adapter
+- **Prism.js** — syntax highlighting for code blocks
+
+### Adding a new page
+
+1. Create a Markdown file in the appropriate `content/` subdirectory
+2. Add frontmatter with `title`, `description`, `section`, and `order`
+3. Add a sidebar link in `app/Shared.elm` under the matching section
+4. The route is automatically generated from the directory and filename
+
+### Key files
+
+| File                               | Purpose                                           |
+| ---------------------------------- | ------------------------------------------------- |
+| `app/Shared.elm`                   | Layout, header, sidebar, search, theme toggle     |
+| `app/Route/Index.elm`              | Home page with package grid                       |
+| `app/Route/Architecture.elm`       | Architecture diagram (SVG)                        |
+| `app/Route/Docs/Slug_.elm`         | Dynamic guide page renderer                       |
+| `app/Route/Packages/Slug_.elm`     | Dynamic package page renderer                     |
+| `app/Route/Contributing/Slug_.elm` | Dynamic contributing page renderer                |
+| `src/MarkdownRenderer.elm`         | Custom Markdown renderer with callout support     |
+| `src/Search.elm`                   | Full-text search index and matching               |
+| `style.css`                        | Stylesheet with CSS custom properties for theming |

apps/docs/app/Route/Architecture.elm

@@ -86,20 +86,44 @@ view app _ =
             ]
         , Html.div [ Attr.class "architecture-diagram" ]
             [ viewDiagram ]
-        , Html.h2 [] [ Html.text "Package Relationships" ]
+        , Html.h2 [] [ Html.text "OIDC DevTools" ]
         , Html.dl []
             [ Html.dt [] [ Html.text "@wolfcola/devtools-types" ]
             , Html.dd []
-                [ Html.text "Effect Schema definitions for AuthEvent and FlowState. Shared foundation used by devtools-bridge." ]
+                [ Html.text "Effect Schema definitions for AuthEvent and FlowState. The shared foundation that all other OIDC packages depend on." ]
+            , Html.dt [] [ Html.text "@wolfcola/devtools-core" ]
+            , Html.dd []
+                [ Html.text "Shared annotators (OIDC phase detection, CORS, DPoP, PAR), diagnosis engine, event store, and export/redaction logic. Used by both the browser extension and VS Code extension." ]
             , Html.dt [] [ Html.text "@wolfcola/devtools-bridge" ]
             , Html.dd []
                 [ Html.text "SDK adapter for emitting events from DaVinci, Journey, and OIDC clients. Depends on devtools-types." ]
-            , Html.dt [] [ Html.text "@wolfcola/treeshake-check" ]
+            , Html.dt [] [ Html.text "@wolfcola/devtools-ui" ]
+            , Html.dd []
+                [ Html.text "Elm UI components for Timeline, Flow, and Learn views. Provides the panel interface with inspector tabs, playback controls, and diagnosis display." ]
+            , Html.dt [] [ Html.text "@wolfcola/devtools-extension" ]
+            , Html.dd []
+                [ Html.text "Chrome and Firefox browser extension. Bundles devtools-core and devtools-ui into a DevTools panel with network-first OIDC detection." ]
+            , Html.dt [] [ Html.text "oidc-devtools (VS Code)" ]
+            , Html.dd []
+                [ Html.text "VS Code extension that connects via Chrome DevTools Protocol (CDP) for live auth traffic capture and flow visualization." ]
+            ]
+        , Html.h2 [] [ Html.text "Tree-Shake Tools" ]
+        , Html.dl []
+            [ Html.dt [] [ Html.text "@wolfcola/treeshake-check" ]
             , Html.dd []
                 [ Html.text "CLI & library to verify packages are tree-shakeable by Rollup. Standalone package." ]
             , Html.dt [] [ Html.text "@wolfcola/eslint-plugin-treeshake" ]
             , Html.dd []
-                [ Html.text "ESLint plugin that flags tree-breaking patterns. Can use treeshake-check for verification." ]
+                [ Html.text "ESLint plugin that flags tree-breaking patterns. Can use treeshake-check for bundle-level verification." ]
+            ]
+        , Html.h2 [] [ Html.text "Utilities" ]
+        , Html.dl []
+            [ Html.dt [] [ Html.text "@wolfcola/dead-export-finder" ]
+            , Html.dd []
+                [ Html.text "CLI to find unused exports across monorepo package boundaries. Uses oxc-parser for fast AST analysis." ]
+            , Html.dt [] [ Html.text "@wolfcola/changeset-sync-manifest" ]
+            , Html.dd []
+                [ Html.text "Internal CI tool that syncs package version from changesets to manifest files. Not documented on the docs site." ]
             ]
         ]
     }
@@ -108,28 +132,47 @@ view app _ =
 viewDiagram : Html.Html (PagesMsg Msg)
 viewDiagram =
     Svg.svg
-        [ SvgAttr.viewBox "0 0 700 360"
-        , SvgAttr.width "700"
-        , SvgAttr.height "360"
+        [ SvgAttr.viewBox "0 0 900 480"
+        , SvgAttr.width "900"
+        , SvgAttr.height "480"
         , SvgAttr.style "max-width: 100%; height: auto;"
         ]
         [ -- OIDC DevTools group
-          svgGroup 20 20 320 300 "OIDC DevTools"
-        , svgBox 60 80 240 60 "devtools-types"
-        , svgBox 60 200 240 60 "devtools-bridge"
+          svgGroup 20 20 520 440 "OIDC DevTools"
+        , svgBox 180 60 200 50 "devtools-types"
+        , svgBox 40 160 200 50 "devtools-core"
+        , svgBox 300 160 200 50 "devtools-bridge"
+        , svgBox 40 270 200 50 "devtools-ui"
+        , svgBox 40 370 200 50 "devtools-extension"
+        , svgBox 300 370 200 50 "vscode-extension"
 
         -- Tree-Shake Tools group
-        , svgGroup 370 20 310 300 "Tree-Shake Tools"
-        , svgBox 400 80 240 60 "treeshake-check"
-        , svgBox 400 200 240 60 "eslint-plugin-treeshake"
+        , svgGroup 570 20 310 200 "Tree-Shake Tools"
+        , svgBox 600 60 240 50 "treeshake-check"
+        , svgBox 600 160 240 50 "eslint-plugin-treeshake"
+
+        -- Utilities group
+        , svgGroup 570 250 310 210 "Utilities"
+        , svgBox 600 290 240 50 "dead-export-finder"
+        , svgBox 600 390 240 50 "changeset-sync-manifest"
+
+        -- Arrows: devtools-types -> devtools-core
+        , svgArrow 230 110 180 160
+
+        -- Arrows: devtools-types -> devtools-bridge
+        , svgArrow 330 110 370 160
+
+        -- Arrows: devtools-core -> devtools-extension
+        , svgArrow 140 210 140 270
 
-        -- Arrows
-        , svgArrow 180 140 180 200
+        -- Arrows: devtools-ui -> devtools-extension
+        , svgArrow 140 320 140 370
 
-        -- devtools-types -> devtools-bridge
-        , svgArrow 520 160 520 200
+        -- Arrows: devtools-core -> vscode-extension
+        , svgArrow 200 210 380 370
 
-        -- treeshake-check -> eslint-plugin-treeshake (optional dependency)
+        -- Arrows: treeshake-check -> eslint-plugin-treeshake
+        , svgArrow 720 110 720 160
         ]
 
 

apps/docs/app/Route/Index.elm

@@ -119,6 +119,12 @@ viewPackageGrid =
             , route = Route.Packages__Slug_ { slug = "devtools-types" }
             , tag = "Published"
             }
+        , viewPackageCard
+            { name = "@wolfcola/dead-export-finder"
+            , description = "CLI to find unused exports across monorepo package boundaries"
+            , route = Route.Packages__Slug_ { slug = "dead-export-finder" }
+            , tag = "Published"
+            }
         ]
 
 

apps/docs/app/Shared.elm

@@ -296,6 +296,7 @@ viewSidebar model toMsg =
             , ( Route.Packages__Slug_ { slug = "eslint-plugin-treeshake" }, "eslint-plugin-treeshake" )
             , ( Route.Packages__Slug_ { slug = "devtools-bridge" }, "devtools-bridge" )
             , ( Route.Packages__Slug_ { slug = "devtools-types" }, "devtools-types" )
+            , ( Route.Packages__Slug_ { slug = "dead-export-finder" }, "dead-export-finder" )
             ]
         , viewSidebarSection "Guides"
             [ ( Route.Docs__Slug_ { slug = "getting-started" }, "Getting Started" )

apps/docs/content/contributing/code-style.md

@@ -7,7 +7,7 @@ order: 3
 
 # Code Style
 
-This repository uses two primary languages: Effect TypeScript for all runtime packages and Elm for the documentation site. Each has its own conventions.
+This repository uses two primary languages: Effect TypeScript for all runtime packages and Elm for both the DevTools panel UI (`devtools-ui`) and the documentation site. Each has its own conventions.
 
 ## Effect TypeScript Conventions
 

apps/docs/content/contributing/repository-structure.md

@@ -21,6 +21,8 @@ The wolfcola-devtools repository is a pnpm workspace monorepo. All publishable p
 | `@wolfcola/devtools-ui`             | `packages/devtools-ui`             | Elm UI components for Timeline, Flow, and Learn views     |
 | `@wolfcola/devtools-extension`      | `packages/devtools-extension`      | Browser extension for Chrome and Firefox                  |
 | `oidc-devtools`                     | `packages/vscode-extension`        | VS Code extension with CDP connection                     |
+| `@wolfcola/dead-export-finder`      | `packages/dead-export-finder`      | CLI to find unused exports across monorepo boundaries     |
+| `@wolfcola/changeset-sync-manifest` | `packages/changeset-sync-manifest` | Syncs package version from changesets to manifest files   |
 | `@wolfcola/docs-site`               | `apps/docs`                        | This documentation site (elm-pages)                       |
 
 ## Root Files
@@ -72,6 +74,12 @@ treeshake-check
 
 eslint-plugin-treeshake
   (standalone, optional dep on treeshake-check)
+
+dead-export-finder
+  (standalone)
+
+changeset-sync-manifest
+  (standalone)
 ```
 
 The `devtools-types` package is the shared foundation. It defines the `AuthEvent` and `FlowState` schemas that the bridge, browser extension, and VS Code extension all depend on.