mp-silma-ai-aide/docs/extension-management.md

# Extension Management

This project builds a Chrome side panel 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 side panel, 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`

## Issue Creation

- Add Issue is enabled only when the active tab's base URL is already in the URLs list and that URL is linked to a Gitea repo.
- The Add Issue view must show the Gitea repo that will receive the issue.
- The Add Issue form must let the user select the agent file for handoff. The initial agent is `GLOBAL AGENT` backed by `AGENTS.md`.
- The Add Issue view intentionally omits the redundant view header title/description and keeps the Ready checkbox label short.
- Screenshot capture uses Chrome's visible-tab capture API and requires the extension's `activeTab` permission plus `<all_urls>` host permission so capture still works after the side panel remains open across tab changes.
- Captured screenshots should appear immediately in Add Issue as thumbnail rows.
- Captured screenshots can be expanded, closed, removed, or cropped before upload.
- File attachments are accumulated across picker selections and all selected files must be uploaded to Gitea.
- Created issue bodies must include `Chrome profile: Silma` and the selected agent.
- Newly created issues must include the `Change Request` label.
- When Ready is checked, create the issue, upload screenshots/files as Gitea issue assets, then apply the `ready` label last.
- The Add Issue view lists existing issues for the linked Gitea repo. Selecting an issue shows the original description, issue attachments, comment chain, and a comment form for text, additional screenshots, and file attachments.
- Issue comments should upload screenshots/files as issue assets first, then create a comment containing links to those attachments.
- Existing issue rows can apply the `ready` label or delete the issue. Deletion must require confirmation.

## URL Management

- URLs can be deleted from the URLs list.
- Deleting a user-added URL removes it from `silmaAide.userUrls` in `chrome.storage.local`.
- Deleting a generated known URL stores its base URL in `silmaAide.deletedUrlBases` so it is hidden without editing generated local context.

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