docs: add extension management guidance

.gitea/workflows/issue-opened-placeholder.yml

@@ -0,0 +1,13 @@
+name: Issue Opened Placeholder
+
+on:
+  issues:
+    types:
+      - opened
+
+jobs:
+  okay:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Report placeholder status
+        run: echo "200 okay"

AGENTS.md

@@ -4,6 +4,11 @@
 
 `mp-silma-ai-aide` is a Vite + TypeScript Chrome extension scaffold. The built `dist/` directory is intended to be loaded in Chrome as an unpacked Manifest V3 extension.
 
+## Required Reading
+
+- Read `docs/extension-management.md` before doing Chrome extension loading, reloading, testing, browser automation, or profile-dependent work.
+- Keep `AGENTS.md`, `llm.txt`, `manifest.llm.json`, `README.md`, and `docs/extension-management.md` in sync when commands, environment variables, deployable output, workflows, or extension-management rules change.
+
 ## Commands
 
 - Install dependencies: `npm ci`
@@ -36,6 +41,17 @@ Use `.env.local` for local secrets. Keep `.env.local` and any real token-bearing
 - Runtime API calls are centralized in `src/api.ts`.
 - Popup state is centralized in the vanilla Zustand store at `src/store.ts`.
 
+## Chrome Extension Management
+
+- Use the Codex Chrome extension with the Chrome profile named `Silma` for this project.
+- Do not use Chrome `Profile 1` for this project.
+- Load or reload the unpacked extension from `dist/` only after running `npm run build`.
+
+## Gitea Workflows
+
+- `.gitea/workflows/build.yml` builds the deployable extension on pushes to `main` and pull requests.
+- `.gitea/workflows/issue-opened-placeholder.yml` runs when a new issue is opened and prints `200 okay`.
+
 ## Coding Guidelines
 
 - Keep the app TypeScript-first and strict.

README.md

@@ -24,6 +24,12 @@ npm run build
 
 The deployable extension output is `dist/`. Load `dist/` in Chrome as an unpacked extension, or point deployment tooling at that folder. `npm run build` runs TypeScript, Vite, and a post-build check that verifies `dist/manifest.json` and the popup entry exist.
 
+## Extension Management
+
+See [docs/extension-management.md](docs/extension-management.md) before loading, reloading, testing, or automating the Chrome extension.
+
+Use the Codex Chrome extension with the Chrome profile named `Silma`. Do not use `Profile 1`.
+
 ## Codex
 
 Codex setup and action commands are declared in `.codex/environments/environment.toml`:
@@ -32,3 +38,8 @@ Codex setup and action commands are declared in `.codex/environments/environment
 - Dev: `npm run dev:codex`
 - Build: `npm run build:codex`
 - Preview: `npm run preview`
+
+## Gitea Workflows
+
+- `.gitea/workflows/build.yml` builds the extension on pushes to `main` and pull requests.
+- `.gitea/workflows/issue-opened-placeholder.yml` runs when a new issue is opened and prints `200 okay`.

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`.

llm.txt

@@ -6,6 +6,7 @@ Important files:
 
 - `AGENTS.md`: Project instructions for coding agents.
 - `manifest.llm.json`: Machine-readable project metadata.
+- `docs/extension-management.md`: Chrome extension management instructions, including the required Chrome profile.
 - `.env.example`: Required environment variables.
 - `vite.config.ts`: Vite build config and generated Chrome extension manifest logic.
 - `src/api.ts`: Axios client and Gitea configuration handling.
@@ -15,6 +16,8 @@ Important files:
 
 Build with `npm run build`. The deployable output directory is `dist/`; load that folder in Chrome as an unpacked extension or point deployment tooling at it. Do not edit `dist/` directly.
 
+Extension management rule: use the Codex Chrome extension with the Chrome profile named `Silma`. Do not use `Profile 1`.
+
 Codex commands:
 
 - Setup: `npm run codex:setup`
@@ -28,3 +31,8 @@ Required env variables:
 - `VITE_GITEA_TOKEN`
 - `VITE_GITEA_REPO_OWNER`
 - `VITE_GITEA_REPO_NAME`
+
+Gitea workflows:
+
+- `.gitea/workflows/build.yml`: build validation for pushes to `main` and pull requests.
+- `.gitea/workflows/issue-opened-placeholder.yml`: new issue placeholder that prints `200 okay`.

manifest.llm.json

@@ -18,6 +18,19 @@
     "vite_config": "vite.config.ts",
     "generated_manifest": "dist/manifest.json"
   },
+  "documentation": {
+    "agent_instructions": "AGENTS.md",
+    "llm_summary": "llm.txt",
+    "readme": "README.md",
+    "extension_management": "docs/extension-management.md"
+  },
+  "extension_management": {
+    "chrome_profile": "Silma",
+    "forbidden_profiles": ["Profile 1"],
+    "codex_chrome_extension_required": true,
+    "load_unpacked_path": "dist/",
+    "instructions": "Use the Codex Chrome extension with the Chrome profile named Silma. Do not use Profile 1."
+  },
   "commands": {
     "install": "npm ci",
     "codex_setup": "npm run codex:setup",
@@ -62,5 +75,17 @@
     "dist/",
     "node_modules/"
   ],
-  "agent_guidance": "See AGENTS.md for coding and build instructions. Do not edit dist/ directly; rebuild from source instead."
+  "gitea_workflows": [
+    {
+      "path": ".gitea/workflows/build.yml",
+      "trigger": "push to main or pull request",
+      "purpose": "Build and verify the deployable extension output."
+    },
+    {
+      "path": ".gitea/workflows/issue-opened-placeholder.yml",
+      "trigger": "new issue opened",
+      "purpose": "Placeholder workflow that prints 200 okay."
+    }
+  ],
+  "agent_guidance": "See AGENTS.md and docs/extension-management.md for coding, build, and Chrome profile instructions. Do not edit dist/ directly; rebuild from source instead."
 }