docs: add extension management guidance

docs/extension-management.md

@@ -0,0 +1,44 @@
+# Extension Management
+
+This project builds a Chrome extension from the generated `dist/` directory. Run `npm run build` before loading or reloading the unpacked extension.
+
+## Required Chrome Profile
+
+When an agent needs to inspect, load, reload, test, or otherwise manage this extension in Chrome, use the Codex Chrome extension with the Chrome profile named `Silma`.
+
+Do not use `Profile 1` for this project.
+
+This rule applies to:
+
+- Opening Chrome for extension work.
+- Loading `dist/` as an unpacked extension.
+- Reloading the extension after a build.
+- Inspecting extension popups, background/service worker behavior, or permissions.
+- Any browser automation that depends on extension state.
+
+## Build Output
+
+- Build command: `npm run build`
+- Deployable/load-unpacked directory: `dist/`
+- Manifest path: `dist/manifest.json`
+
+Do not edit `dist/` directly. Change source files and rebuild.
+
+## Environment
+
+Use `.env.local` for local extension configuration and secrets. Never commit real tokens.
+
+Required variables:
+
+- `VITE_GITEA_BASE_URL`
+- `VITE_GITEA_TOKEN`
+- `VITE_GITEA_REPO_OWNER`
+- `VITE_GITEA_REPO_NAME`
+
+## Agent Checklist
+
+1. Run `npm run build`.
+2. Confirm `npm run verify:dist` passes.
+3. Use the `Silma` Chrome profile through the Codex Chrome extension.
+4. Load or reload the `dist/` directory.
+5. Avoid `Profile 1`.