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.
• Add Issue and selected issue editing expose these label options: Change Request, Idea, Tabitha, Orson, Belisarius, Ozymandias, and Ready.
• New issues default to Change Request selected unless the user changes the label selection.
• Do not show the old Ready checkbox; Ready is now a selectable label.
• 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 use the selected labels.

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/label fields, issue attachments, direct attachment upload controls, 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, save labels through Gitea's issue labels endpoint, 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.
• Additional selected-issue screenshots/files can also be uploaded directly as issue assets without creating a comment.
• Existing issue attachments can be deleted from the selected issue.
• Existing issue rows can delete the issue. Issue labels are edited in the selected issue form. 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.