docs: add project and architecture guides

.changeset/1f06f2c5.md

@@ -0,0 +1,5 @@
+---
+"@mynameistito/opencode-plugins-docs": patch
+---
+
+Add project and architecture documentation

.github/workflows/link-check.yml

@@ -28,7 +28,7 @@ jobs:
         uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2
         with:
           args: >-
-            --verbose --no-progress --max-retries 3 --retry-wait-time 2 --timeout 20 --include-mail=false --accept 200,206,301,302,307,308,429 --exclude-path 'apps/web/docs/index\.mdx$' README.md 'apps/web/**/*.md' 'apps/web/**/*.mdx' 'packages/*/README.md'
+            --verbose --no-progress --max-retries 3 --retry-wait-time 2 --timeout 20 --include-mail=false --accept 200,206,301,302,307,308,429 --root-dir apps/web/docs --fallback-extensions md,mdx --exclude-path 'apps/web/docs/index\.mdx$' README.md 'apps/web/**/*.md' 'apps/web/**/*.mdx' 'packages/*/README.md'
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Check homepage links against production

.lycheeignore

@@ -1,4 +1,6 @@
 ^https://www\.npmjs\.com/package/@opencode/cli/?$
+^https://www\.npmjs\.com/package/@mynameistito/opencode-force-input/?$
+^https://www\.npmjs\.com/package/@mynameistito/opencode-usage-limits/?$
 ^https://chatgpt\.com/?$
 ^https://github\.com/modelstudioai/cli/blob/main/packages/commands/src/commands/usage/token-plan\.ts$
 ^https://github\.com/mynameistito/opencode-plugins/blob/main/packages/opencode-usage-limits/examples/usage-limits\.jsonc$

README.md

@@ -43,6 +43,10 @@ opencode2 plugin add "@mynameistito/opencode-usage-limits@latest" -g
 
 See the [usage-limits README](packages/opencode-usage-limits/README.md) for provider credentials, configuration, and troubleshooting.
 
+## Project Documentation
+
+The documentation site source lives in [`apps/web/docs/`](apps/web/docs/). Start with the [project overview](apps/web/docs/project.mdx) for the repository layout and packages, or read the [architecture guide](apps/web/docs/architecture.mdx) for plugin runtime flows and deployment boundaries. The same guides are available on the [documentation site](https://opencode-plugins.mynameistito.com/).
+
 ## Local Development
 
 Build the workspace and load the source entrypoints from `~/.config/opencode/cli.json`:

apps/web/blume.config.ts

@@ -51,6 +51,8 @@ export default defineConfig({
   navigation: {
     sidebar: [
       "/",
+      "/project",
+      "/architecture",
       "/force-input",
       "/usage-limits",
       "/development",

apps/web/docs/architecture.mdx

@@ -0,0 +1,52 @@
+---
+title: Architecture
+description: Runtime boundaries and data flow for the OpenCode plugins and documentation site.
+sidebar:
+  label: Architecture
+  order: 3
+---
+
+The repository has two separately published TUI plugins and a documentation app. Each plugin runs inside the OpenCode terminal UI and contributes a focused interaction. The website is a separate static site and is not required at plugin runtime.
+
+## Plugin boundaries
+
+```text
+OpenCode v2 TUI
+├── Force Input
+│   ├── keymap layer: Ctrl+Enter / Ctrl+Return
+│   └── prompt-footer slot: state-aware hint
+└── Usage Limits
+    ├── configuration + OpenCode auth
+    ├── provider adapters and runtime services
+    ├── refresh coordinator + latest snapshot
+    └── sidebar and prompt-footer slots
+```
+
+Both packages declare their TUI entrypoint separately from any server plugin interface. OpenCode owns the plugin lifecycle and supplies session, theme, keymap, and UI-slot context.
+
+## Force Input flow
+
+The plugin registers high-priority bindings for both common Ctrl+Enter key names. When invoked, it dispatches OpenCode's guarded `session.interrupt` command three times and then dispatches `prompt.submit`. The host decides whether the submitted prompt steers the active session or starts a new turn. The footer hint follows the session state and is hidden in shell mode or when there is no applicable composer.
+
+## Usage Limits flow
+
+1. The plugin loads its JSONC configuration and OpenCode authentication data.
+2. Enabled providers are fetched through provider-specific adapters. Adapters normalize API or authenticated-CLI results into common usage windows and balances.
+3. A coordinator refreshes on the configured interval, retains successful snapshots, and records provider errors without exposing credentials or response bodies in the UI.
+4. The sidebar renders configured provider results. The prompt footer selects a compact result based on the active session's provider.
+
+Provider adapters are isolated from rendering. This keeps provider-specific response parsing and credential handling out of the UI components. See [Usage Limits](/usage-limits) for provider-specific credential rules and supported windows.
+
+## Documentation and deployment
+
+The site under `apps/web/` reads its Markdown/MDX content from `apps/web/docs/`. Blume builds the site into `apps/web/dist/`, while Alchemy's `Website.StaticSite` deploys those assets to Cloudflare. The production custom domain is configured in `apps/web/alchemy.run.ts`; content and build settings are configured in `apps/web/blume.config.ts`.
+
+The website and plugins have independent release/deployment paths: Changesets describe package releases, and the deployment workflow publishes the documentation site. Documentation content should be checked with the web app's test/build scripts and accompanied by a `docs` Changeset when it is user-facing site content.
+
+## Source map
+
+- `packages/opencode-force-input/src/`: keybinding registration, hint state, and TUI entrypoint.
+- `packages/opencode-usage-limits/src/`: plugin lifecycle, UI components, configuration, coordinator, provider adapters, and shared types.
+- `apps/web/docs/`: website content.
+- `apps/web/blume.config.ts`: content sources, navigation, site metadata, and generated agent docs.
+- `apps/web/alchemy.run.ts`: static-site build and Cloudflare deployment declaration.

apps/web/docs/index.mdx

@@ -47,6 +47,8 @@ opencode2 plugin list
 
 ## Project links
 
+- [Project overview](/project)
+- [Architecture](/architecture)
 - [Source repository](https://github.com/mynameistito/opencode-plugins)
 - [Force Input guide](/force-input)
 - [Usage Limits guide](/usage-limits)

apps/web/docs/project.mdx

@@ -0,0 +1,49 @@
+---
+title: Project overview
+description: How the OpenCode Plugins repository and its packages are organized.
+sidebar:
+  label: Project overview
+  order: 2
+---
+
+This repository contains focused [OpenCode v2](https://opencode.ai/v2) TUI plugins and the documentation site that explains how to install and use them. The plugins extend the terminal interface; they do not replace models, prompts, or OpenCode server configuration.
+
+## Packages
+
+| Package | Purpose | Published entrypoints |
+| --- | --- | --- |
+| [`@mynameistito/opencode-force-input`](https://www.npmjs.com/package/@mynameistito/opencode-force-input) | Interrupt an active run and submit the current prompt with `Ctrl+Enter` or `Ctrl+Return`. | `./tui` |
+| [`@mynameistito/opencode-usage-limits`](https://www.npmjs.com/package/@mynameistito/opencode-usage-limits) | Show supported provider usage windows and balances in the sidebar and prompt footer. | `./tui`, `./schema` |
+
+The package READMEs and the [plugin guides](/force-input) and [usage guide](/usage-limits) are the detailed user-facing references. Package versions are released independently.
+
+## Repository layout
+
+```text
+packages/
+  opencode-force-input/   Force Input plugin source, tests, and package metadata
+  opencode-usage-limits/  Usage Limits plugin source, tests, schema, and examples
+apps/
+  web/                    Blume documentation site and Cloudflare deployment
+.changeset/               Pending package release and documentation notes
+```
+
+The root `package.json` defines the Bun workspace and common checks. Each package owns its runtime dependencies, build, tests, and published files. The website content is sourced from `apps/web/docs/` and its release history is generated from GitHub releases.
+
+## Technology and compatibility
+
+- **OpenCode v2 TUI plugin API** provides keybindings, session context, and UI slots.
+- **TypeScript** is used for plugin implementations; Usage Limits uses Effect for provider runtime workflows.
+- **Bun workspaces** manage installation and run the repository's scripts.
+- **Blume** builds the documentation site, including searchable and agent-oriented documentation outputs.
+- **Alchemy** deploys the static site to Cloudflare Workers assets.
+
+The plugins target OpenCode v2 and are distributed through npm. Consult each package's README for current installation instructions, configuration, provider support, and troubleshooting.
+
+## Start here
+
+- [Force Input](/force-input): keybinding behavior and configuration.
+- [Usage Limits](/usage-limits): providers, credentials, display, and configuration.
+- [Architecture](/architecture): runtime boundaries and data flow.
+- [Development and releases](/development): local commands, checks, and deployment.
+- [Source repository](https://github.com/mynameistito/opencode-plugins)