feat(plugins): add plugin architecture

.github/workflows/deploy-docs.yaml

@@ -0,0 +1,57 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/deploy-docs.yaml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Mintlify CLI
+        run: npm install -g mintlify@latest
+
+      - name: Build documentation
+        run: |
+          cd docs
+          mintlify build
+          # Ensure .nojekyll is present for GitHub Pages
+          touch .mintlify/dist/.nojekyll
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs/.mintlify/dist'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

.github/workflows/ext-check.yml

@@ -0,0 +1,18 @@
+name: Extensions Check
+
+on:
+  pull_request:
+    branches: [ "*" ]
+
+jobs:
+  ext-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - run: npm ci
+      - run: npm run ext:check
+
+

.gitignore

@@ -106,7 +106,28 @@ external/superhero-ui-vue-for-reference/node_modules/
 # Banner suggestions (design mockups)
 banner-suggestions/
 
-# Python virtual environment for docs
+# --- Python docs tooling ---
+# Local virtual environments
+.venv/
+.venv-*/
+venv/
+venv-*/
 .venv-docs/
+docs/.venv/
+docs/venv/
+
+# Documentation build outputs (legacy MkDocs - kept for reference)
+site/
+docs/site/
+site-docs/
+
+# Mintlify build artifacts (generated by `mintlify build`)
+.mintlify/
+docs/.mintlify/
+
+# Python caches
+__pycache__/
+*.pyc
+.pytest_cache/
 
 

README.md

@@ -99,6 +99,15 @@ This app is a static site once built. You can deploy the `dist/` directory to an
 - Netlify configuration is included: `netlify.toml` and `public/_redirects` for SPA routing
 - Typical build settings: build command `npm run build`, publish directory `dist`
 
+## Extending with Plugins
+
+See `docs/plugin-sdk.md` for the public plugin SDK. It covers:
+
+- Feed plugins (new entry kinds)
+- Composer actions and attachments (inline panels such as Poll)
+- Item actions, routes and modals
+- Runtime loading and capability gating
+
 ## Contributing
 
 1. Create a feature branch from `main`

docs/README.md

@@ -0,0 +1,73 @@
+# Superhero Documentation
+
+**Live Documentation**: [docs.superhero.com](https://docs.superhero.com)
+
+This directory contains the source files for the Superhero plugin development documentation, built with [Mintlify](https://mintlify.com).
+
+## Run Documentation Locally
+
+To preview the documentation locally during development:
+
+```bash
+# Install Mintlify CLI globally (requires Node.js v19+)
+npm i -g mintlify
+
+# Start local development server
+cd docs
+mintlify dev --port 3002
+```
+
+The documentation will be available at `http://localhost:3002`.
+
+### Build Static Files
+
+To build the documentation for production:
+
+```bash
+cd docs
+mintlify build
+```
+
+The static files will be generated in `docs/.mintlify/dist/`.
+
+## Deployment
+
+The documentation is automatically deployed to GitHub Pages at `docs.superhero.com` when changes are pushed to the `main` branch.
+
+### Automatic Deployment
+
+The GitHub Actions workflow (`.github/workflows/deploy-docs.yaml`) automatically:
+- Builds the documentation using Mintlify
+- Deploys to GitHub Pages on pushes to `main` that affect the `docs/` directory
+- Supports manual deployment via Actions → "Deploy Documentation to GitHub Pages" → Run workflow
+
+### GitHub Pages Setup
+
+To enable GitHub Pages deployment:
+
+1. **Enable GitHub Pages** in repository settings:
+   - Go to Settings → Pages
+   - Source: GitHub Actions
+   - Custom domain: `docs.superhero.com` (optional)
+
+2. **Configure Custom Domain** (if using `docs.superhero.com`):
+   - Add a CNAME record pointing `docs.superhero.com` to `your-org.github.io`
+   - Or add an A record pointing to GitHub Pages IP addresses
+   - Enable "Enforce HTTPS" in GitHub Pages settings
+
+## Documentation Structure
+
+- `mint.json` - Mintlify configuration (navigation, branding, etc.)
+- `tutorials/hackathon/` - Plugin development tutorials and guides
+- `plugin-sdk.md` - Plugin SDK API reference
+- `index.md` - Main documentation landing page
+
+## Contributing
+
+When contributing to the documentation:
+
+1. Edit the Markdown files in this directory
+2. Test locally using `mintlify dev --port 3002`
+3. Commit changes to `main` branch to trigger automatic deployment
+4. Verify deployment at `docs.superhero.com`
+

docs/_archive/EXTENSIONS.md

@@ -0,0 +1,79 @@
+# Superhero App Extensions
+
+> [!NOTE]
+> For a step-by-step walkthrough, see [How to build a Superhero App Extension (Polls example)](./tutorials/build-governance-poll-extension.md).
+
+Extensions are first-class modules that can add routes, menu items, feed entries, composer actions, item actions, modals, and composer attachments. They are authored with the existing plugin SDK and loaded at runtime.
+
+## Capabilities
+- routes: add pages (mounted dynamically via routeRegistry)
+- menu: add header navigation items (merged via navRegistry)
+- feed: contribute feed entries and renderers
+- composer: add composer actions and attachments
+- item-actions: add per-feed-item actions
+- modals: register modal components
+
+## Authoring an extension
+Minimal example:
+```tsx
+import React from 'react';
+import { definePlugin } from '@/plugin-sdk';
+import MyApp from './ui/MyApp';
+
+export default definePlugin({
+  meta: {
+    id: 'my-ext',
+    name: 'My Extension',
+    version: '0.1.0',
+    apiVersion: '1.x',
+    capabilities: ['routes', 'menu', 'composer'],
+  },
+  setup({ register }) {
+    register({
+      routes: [{ path: '/my-ext', element: <MyApp /> }],
+      menu: [{ id: 'my-ext', label: 'My Ext', path: '/my-ext', icon: '🧩' }],
+      // attachments: () => [myAttachmentSpec],
+    });
+  },
+});
+```
+
+## Loading modes
+- Local (first‑party): register in `src/plugins/local.ts` for development. Not enabled by default in production.
+- External (remote URLs): `CONFIG.PLUGINS` can point to remote modules. The loader enforces the `capabilities` allowlist.
+
+## Capability allowlist
+- Use `CONFIG.PLUGIN_CAPABILITIES_ALLOWLIST` to restrict what plugins may register, e.g. `['routes','feed','composer']`.
+
+## Registries lifecycle
+- Registries live in `features/social/plugins/registries.ts`.
+- In development, local loader resets registries on hot reload to avoid duplicates.
+- Plugin bootstrap is guarded to run once per app lifecycle.
+
+## Contracts
+Use `createContractLoader(sdk)` from `src/extensions/contract.ts` to load ACI-based contract instances.
+
+## Backend integration
+Point your extension to backend services. For Social Superhero governance backend, see:
+- repo: https://github.com/superhero-com/superhero-api
+- flow: index chain data → expose REST/WebSocket → consume from extension client
+
+## Environment & config
+- `public/superconfig.json` (or `window.__SUPERCONFIG__`) provides runtime keys like `NODE_URL`, `MIDDLEWARE_URL`, `GOVERNANCE_API_URL`, `PLUGINS`, `PLUGIN_CAPABILITIES_ALLOWLIST`.
+
+## CI
+- `npm run ext:check` validates extension modules. The CI workflow runs it on pull requests.
+
+## Security & UX notes
+- Keep capabilities minimal; prefer read-only routes for untrusted plugins.
+- Gating composer/actions behind the allowlist reduces risk.
+- Validate inputs and handle network failures gracefully.
+
+## Troubleshooting
+- Duplicate nav or routes: ensure bootstrap runs once; in dev registries are reset before loading local plugins.
+- Wallet not connected: ensure wallet connect flow completes before signing.
+- ACI mismatch: recompile and update contract address.
+
+## Full tutorial (Polls example)
+See the detailed guide:
+`docs/tutorials/build-governance-poll-extension.md`

docs/_archive/backend-integration.md

@@ -0,0 +1,26 @@
+# Backend Integration for App Extensions
+
+This guide explains how to integrate an extension with a backend service. For Social Superhero, we reference the `superhero-api` repository.
+
+## When to use a backend
+- Indexing historical data and building feeds
+- Search and rich queries
+- WebSocket push updates
+- Off-chain validation
+
+## Setup superhero-api
+- Repo: https://github.com/superhero-com/superhero-api
+- Quick start (Docker): see repository README
+- Configure ENV in frontend: `VITE_EXT_<YOUR_EXT>_API_URL`
+
+## Client in extension
+Create a small client under `src/plugins/<id>/client/backend.ts` and read the base URL from `VITE_EXT_<ID>_API_URL` or runtime `__SUPERCONFIG__`.
+
+## Patterns
+- Pagination tokens instead of page numbers
+- Idempotent POSTs, signed requests where needed
+- WebSocket channels for live updates
+
+## Error handling
+- Map HTTP errors to user-friendly messages
+- Retry with backoff