docs: consolidate (#5)

Author: harley

README.md

@@ -43,6 +43,10 @@ pnpm run build
 
 The production bundle lands in `build/`. Package it manually or use `pnpm run zip` for a distributable archive located in `package/`.
 
+## Releases
+
+Release Please manages versioning and release notes. Check the autogenerated root `CHANGELOG.md` or the GitHub Releases tab for the latest history.
+
 ---
 
 Bootstrapped with [create-chrome-ext](https://github.com/guocaoyi/create-chrome-ext)

docs/README.md

@@ -23,7 +23,8 @@ Additional scripts live in `package.json`, including `pnpm build` for production
 - [Extension Flow](./extension-flow.md)
 - [UI Guidelines](./ui-guidelines.md)
 - [Testing Guide](./testing.md)
-- [Changelog](./changelog.md)
+
+Release notes are generated automatically via release-please and published with GitHub Releases; there is no manual changelog in this folder.
 
 ## Doc Conventions
 

docs/architecture.md

@@ -2,6 +2,8 @@
 
 CoderChart follows the typical MV3 separation: a background service worker maintains defaults, the content script renders diagrams in-page, and the options UI manages configuration. Shared utilities in `src/shared` allow all surfaces to agree on settings and URL matching.
 
+For a user-centric walkthrough of the lifecycle, see [`extension-flow.md`](./extension-flow.md).
+
 ## Runtime Components
 
 - **Background (`src/background/index.ts`)**
@@ -25,7 +27,7 @@ CoderChart follows the typical MV3 separation: a background service worker maint
 
 ```mermaid
 flowchart TD
-    A[Load content script] --> B[getSettings()]
+    A[Load content script] --> B[Fetch settings]
     B --> C{autoRender enabled?}
     C -- No --> D[Stay idle]
     C -- Yes --> E{URL matches whitelist?}
@@ -55,5 +57,6 @@ flowchart TD
 
 ## Known Constraints
 
-- Builds occasionally report Rollup chunk-size warnings; adjust splitting before release if bundle size grows.
-- Rendering currently assumes Mermaid syntax; invalid diagrams surface an inline error but do not retry automatically.
+- Clearing all host patterns in options is not persisted: `normalizeSettings` restores the default ChatGPT domains, so disable `autoRender` to pause rendering globally.
+- PNG export relies on drawing the generated SVG into a canvas; diagrams that pull in external assets or exceed canvas limits can fail to export and log a warning.
+- Mermaid parse failures surface inline with a copyable fix prompt, but there is still no automatic retry or self-healing.

docs/changelog.md

@@ -1,17 +1,17 @@
 # Extension Flow
 
-This guide walks through the end-to-end experience from installation to exporting rendered diagrams.
+This guide outlines the user-visible lifecycle. For component responsibilities and deeper mechanics, see [`architecture.md`](./architecture.md).
 
-## Narrative Flow
+## Lifecycle Overview
 
-1. **Install:** User loads the unpacked build or installs from the Chrome Web Store. The background script seeds default settings in `chrome.storage.sync`.
-2. **Grant permissions:** Chrome applies host permissions declared in `manifest.ts` (ChatGPT domains and localhost during development).
-3. **Open supported page:** When the user opens chatgpt.com or another whitelisted host, the content script loads, retrieves settings, and checks the URL against the whitelist.
-4. **Render diagrams:** Matching Mermaid code fences trigger the inline renderer. Mermaid initialises with theme selection, generates SVG, and injects a container with toolbar controls.
-5. **Adjust settings:** Users can visit `options.html` to disable auto-rendering, edit host patterns, or reset to defaults. Changes sync across devices.
-6. **Use toolbar:** Inline buttons allow collapsing/expanding the diagram, scrolling back to the source code block, and exporting as SVG or PNG.
-7. **Download pipeline:** SVG downloads reuse the cached render, while PNG downloads convert the SVG via an off-screen canvas before prompting a file save.
-8. **Keep updated:** A MutationObserver re-runs rendering when the chat adds new content, and storage listeners reconfigure the script when settings change.
+| Step | Trigger | Primary owner | Notes |
+| --- | --- | --- | --- |
+| Install or upgrade | Extension installed from source or Web Store | Background service worker | Seeds defaults and handles migrations (`architecture.md` → Runtime Components). |
+| Host access granted | Chrome applies `manifest.ts` host permissions | Chrome / MV3 platform | Controls where the content script can run (`architecture.md` → Runtime Components). |
+| Page activation | User opens a whitelisted URL | Content script | Fetches settings, checks URL against patterns, and, if allowed, initialises Mermaid (`architecture.md` → Data Flow Sequence). |
+| Inline rendering | Mermaid blocks detected | Content script + Mermaid runtime | Injects managed containers, themes Mermaid, and caches SVG output (`architecture.md` → Mermaid Rendering & Downloads). |
+| Settings changes | Options UI edits or resets settings | Options UI + shared settings utils | Saves updates through `saveSettings`; listeners reconcile state across surfaces (`architecture.md` → Settings Synchronisation). |
+| Continuous updates | Chat adds new content or settings sync changes arrive | Content script | MutationObserver re-runs detection; storage listeners reapply activation rules (`architecture.md` → Settings Synchronisation). |
 
 ## Sequence Diagram
 
@@ -21,7 +21,8 @@ sequenceDiagram
     participant C as Chrome
     participant B as Background
     participant CS as Content Script
-    participant Opt as Options UI
+    participant Options as Options UI
+    participant Toolbar as Download Toolbar
 
     U->>C: Install extension
     C->>B: fire onInstalled
@@ -40,8 +41,8 @@ sequenceDiagram
     U->>Toolbar: Click download SVG/PNG
     Toolbar->>CS: fetch cached SVG / convert to PNG
     CS->>U: Trigger file download
-    U->>Opt: Open options page
-    Opt->>chrome.storage.sync: save updated settings
+    U->>Options: Open options page
+    Options->>chrome.storage.sync: save updated settings
     chrome.storage.sync-->>CS: onChanged event
     CS->>CS: Apply settings (activate/deactivate/re-render)
 ```