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, 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. It currently contains one entry: GLOBAL AGENT backed by AGENTS.md.
• 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, let the user select an agent file, 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.
• Newly created issues must be created with the Change Request label.
• If the Ready checkbox is checked, create the issue first, upload screenshots/files as issue assets second, and apply the ready label last.
• The Add Issue view also lists existing issues for the linked Gitea repo. Selecting an issue must show the original description, issue attachments, and comment chain, followed by 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.
• Existing issue rows must allow applying the ready label and deleting the issue. Deletion must require user confirmation.
• Keep the Add Issue view dense; do not show the redundant view header title/description inside this view, and keep the Ready checkbox label short.
• 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.