mp-silma-ai-aide/AGENTS.md

AGENTS.md

Project

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
• Codex setup: npm run codex:setup
• Run local Vite dev server: npm run dev
• Run app in Codex: npm run dev:codex
• Build extension: npm run build
• Build extension in Codex: npm run build:codex
• Preview build output: npm run preview
• Verify generated extension output: npm run verify:dist

Environment

Configuration is read from Vite environment variables:

• VITE_GITEA_BASE_URL: Base URL for the Gitea instance, for example http://gitea.orson.tealthrone.
• VITE_GITEA_TOKEN: Gitea API token.
• VITE_GITEA_REPO_OWNER: Target Gitea owner. Default: jacob-mathison.
• VITE_GITEA_REPO_NAME: Target Gitea repository. Default: mp-silma-ai-aide.

Use .env.local for local secrets. Keep .env.local and any real token-bearing env files out of git. Update .env.example when adding new required variables.

Extension Build Notes

• vite.config.ts emits dist/manifest.json during production builds.
• dist/ is the deployable output directory. Deployment or Chrome load-unpacked flows should point directly at dist/.
• dist/ is generated output and should not be edited directly.
• Static extension assets live in public/; extension icon sources live under public/icons/.
• scripts/generate-local-context.mjs generates public/local-context.json from /Users/Tabitha/.openclaw/workspace_Father before builds.
• public/local-context.json is a committed fallback snapshot so CI builds can still produce a self-contained dist/ if the local workspace root is unavailable.
• npm run build runs scripts/verify-dist.mjs after Vite to ensure the generated output has the required extension files.
• Host permissions include <all_urls> for Chrome visible-tab screenshot capture plus the Gitea host derived from VITE_GITEA_BASE_URL. Rebuild after changing the base URL.
• Runtime API calls are centralized in src/api.ts.
• Side panel state is centralized in the vanilla Zustand store at src/store.ts.
• The extension opens as a Chrome side panel. It is not a draggable in-page window.
• The side panel has icon menu sections for Add URL, URLs, Gitea repos, Workspaces, Agents, Open Issues, and Add Issue.
• Add URL is enabled only when the active tab's base URL is not already in the URLs list. The user must pick either a workspace or a Gitea repo; the app infers the linked counterpart from local context.
• URLs can be deleted from the URLs list. User-added URLs are removed from storage; generated known URLs are hidden through the stored deleted-base list.
• The Agents view lists available agent files and must allow adding, editing, and deleting persisted agents from chrome.storage.local. At least one agent must remain available.
• The default GLOBAL AGENT is backed by AGENTS.md and contains agnostic handoff rules with template variables such as {{git}}, {{workspace}}, {{url}}, {{baseUrl}}, {{profile}}, and {{issue}}.
• Add Issue is enabled only when the active tab's base URL is already in the URLs list and has a linked Gitea repo. The issue form must show the target repo, the active URL the extension believes it is attached to, let the user select an agent file and issue labels, capture visible-tab screenshots, accept multiple accumulated Gitea-friendly file attachments, and include Chrome profile: Silma plus the selected agent in created issue bodies.
• Clicking a captured screenshot must open an expanded preview with Close, Remove, and Crop controls. The crop area should be a simple draggable/resizable box without a shaded crop fill, and the preview panel should use the available viewport without horizontal scrolling.
• Label options for issue creation and editing are Change Request, Idea, Tabitha, Orson, Belisarius, Ozymandias, and Ready.
• Newly created issues must default to the Change Request label unless the user changes the selected labels.
• When creating an issue, upload the selected rendered agent file as an issue asset along with screenshots and files.
• The old Ready checkbox must not be shown because Ready is now one of the selectable labels.
• Open Issues owns issue browsing and follow-up. It must list recent issues ordered by creation time, default to open issues for the active URL's linked repo, provide a checkbox to show issues across all loaded repos, and provide a status dropdown for Open, Closed, or Open + Closed.
• Selecting an Open Issues row must show a direct Open in Gitea link, editable issue subject/content/label fields, issue attachments, and comment chain, followed by direct issue attachment controls plus a comment form that can add text, take additional screenshots, attach files, upload those files as issue assets, and submit a Gitea comment with attachment links.
• Saving selected issue edits must use the selected issue's repo identity from Open Issues and must never fall back to the active tab's repo.
• Existing issue rows must allow deleting the issue. Existing issue labels must be editable from the selected issue form and saved through the Gitea issue labels endpoint. Existing issue attachments must be removable, and additional screenshots/files must be uploadable directly to the issue without creating a comment. Deletion must require user confirmation.
• Text-entry updates in Add Issue, selected issue edits, Open Issues comments, and Agents must not re-render the focused form control or blur the user while they type.
• Keep the Add Issue view dense; do not show the redundant view header title/description inside this view.
• The extension requests activeTab and <all_urls> host permission so screenshots can be captured from the current Chrome tab even after the side panel has stayed open across tab changes.

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.
• Prefer small, focused modules under src/.
• Do not commit secrets or generated build output.
• Run npm run build before handing off code changes.