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 and the active URL the extension believes it is attached to.
- The Add Issue form must let the user select the agent file for handoff. Agents are managed in the Agents view, persisted in `chrome.storage.local`, and 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. The crop UI should use a plain draggable/resizable crop box instead of shaded slider-based controls, and the preview panel should fit the available viewport without horizontal scrolling.
- 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.
- Created issues must upload the selected rendered agent file as a Gitea issue asset. Supported template variables in agent content are `{{git}}`, `{{repo}}`, `{{workspace}}`, `{{url}}`, `{{baseUrl}}`, `{{profile}}`, and `{{issue}}`.
- Newly created issues must include the `Change Request` label.
- When Ready is checked, create the issue, upload the rendered agent file plus screenshots/files as Gitea issue assets, then apply the `ready` label last.

## Open Issues

- Open Issues owns existing issue browsing and follow-up comments.
- The primary Open Issues panel lists recent issues ordered by creation time.
- The `Only current repo` checkbox defaults to checked and limits the table to the active URL's linked Gitea repo.
- Turning off `Only current repo` loads recent issues from all repos already loaded in the extension.
- The status dropdown defaults to `Open` and supports `Open`, `Closed`, and `Open + Closed`.
- Selecting an issue shows a direct Open in Gitea link, editable issue subject/content fields, issue attachments, comment chain, and a comment form for text, additional screenshots, and file attachments.
- Saving selected issue edits must use the repo identity from the selected Open Issues row and must not fall back to the active tab's repo.
- Issue comments should upload screenshots/files as issue assets first, then create a comment containing links to those attachments.
- Existing issue attachments can be deleted from the selected issue.
- Existing issue rows can apply the `ready` label or delete the issue. Deletion must require confirmation.
- Typing in Add Issue, selected issue edit fields, Open Issues comments, or Agents editor fields must not blur the focused control.

## 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 Management

- The Agents view must allow adding, editing, and deleting agent files.
- At least one agent must remain available so Add Issue always has a handoff file.
- Agent records are persisted in `silmaAide.agents`.
- The default `GLOBAL AGENT` should remain agnostic and use template variables instead of hard-coded project paths where possible.

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