docs(agents): add repository guidance

AGENTS.md

@@ -0,0 +1,220 @@
+# Tailchat Agent Guide
+
+## Scope and priorities
+
+This file applies to the entire repository. It is guidance for coding agents,
+not a replacement for `README.md`, `README.zh.md`, or the long-form website
+documentation. A direct user request always takes precedence.
+
+Tailchat is a noIM platform: messaging is the collaboration core and plugins
+are first-class product extensions. Preserve that model when choosing where a
+change belongs.
+The primary runtime flow is:
+
+1. The web entry configures shared adapters and loads MiniStar plugins.
+2. React UI calls APIs, Socket.IO, state, and domain helpers in `client/shared`.
+3. The gateway maps HTTP or socket requests to Moleculer `TcService` actions.
+4. Services validate, authenticate, authorize, coordinate, and access models.
+5. Notifications return through Socket.IO and update shared client state.
+
+Do not bypass this flow by coupling core UI to plugin internals, accessing data
+around service actions, or relying on client-side authorization.
+
+## Repository map
+
+- `client/web`: browser application, routes, browser integration, and plugin host.
+- `client/shared`: cross-platform API, socket, state, hooks, models, and utilities.
+- `client/packages`: frontend design system, client SDK, and build-time tooling.
+- `client/web/plugins`: pure frontend plugins and their manifests.
+- `server/services`: core and OpenAPI Moleculer services.
+- `server/models`: Typegoose persistence models.
+- `server/packages/sdk`: `TcService`, gateway, permission, runner, and SDK contracts.
+- `server/plugins`: backend or full-stack plugins, sometimes with embedded web UI.
+- `server/admin`: separate Vite/React frontend and Express admin service.
+- `packages/types`: published structures shared across package boundaries.
+- `client/desktop`: current Electron shell; it loads a Tailchat web deployment.
+- `client/mobile`: React Native WebView shell and native bridges.
+- `client/desktop-old`: legacy implementation; do not use it as the default target.
+- `apps`: non-core CLI, GitHub app, OAuth demo, and embeddable widget.
+- `website`: Docusaurus documentation and marketing site.
+
+Read the nearest package scripts and local documentation before editing. Some
+subprojects have distinct build systems even when their source lives here.
+
+## Working protocol
+
+1. Start with `git status --short --branch --untracked-files=all`.
+2. Trace the real entry point, caller, contract, and tests before changing code.
+3. Follow an existing service, model, component, or plugin pattern when possible.
+4. Make the smallest coherent change; avoid unrelated cleanup and refactoring.
+5. Preserve unrelated staged, unstaged, ignored, and untracked user work.
+6. Add or update focused tests beside the behavior being changed.
+7. Run checks proportional to the affected subsystem.
+8. Report exact commands, failures, skipped checks, and environment blockers.
+
+Do not run repository-wide `pnpm lint:fix` by default. It can rewrite files
+outside the task. Lint or format only files in scope.
+
+Do not edit `node_modules`, `dist`, `build`, coverage output, or generated
+runtime assets as source. Do not use a generated file to avoid fixing its owner.
+
+## Toolchains and package ownership
+
+CI and Docker define the main baseline: Node.js 18 and pnpm 8.15.8. A newer
+machine-local Node or pnpm version does not expand supported compatibility.
+
+Use pnpm for the root workspace. Install with:
+
+```bash
+pnpm install --frozen-lockfile
+```
+
+The root `pnpm dev` starts the server and web development processes. Local
+development also needs the configured MongoDB, Redis, and MinIO dependencies;
+the default web and gateway ports are 11011 and 11000.
+
+`client/desktop`, `client/mobile`, and `client/desktop-old` keep independent
+Yarn lockfiles. Run Yarn from the owning directory and do not rewrite those
+locks with pnpm.
+
+Dependency changes must update the owning manifest and matching lockfile. Avoid
+lockfile churn unrelated to the requested dependency change.
+
+## Frontend rules
+
+- Keep plugin initialization before application rendering in `client/web`.
+- Use `client/shared` only for behavior that is genuinely cross-platform.
+- Keep DOM, browser, Electron, and React Native behavior in platform layers.
+- Reuse shared request and socket wrappers; preserve token and error handling.
+- Keep remote-event to local-state synchronization in the established Redux flow.
+- Reuse existing design components and registration APIs before adding globals.
+- User-visible core strings use existing `t`, `Trans`, and translation workflows.
+- Frontend permission checks control presentation only, never final authorization.
+
+The web TypeScript configuration excludes plugin source. A successful core web
+type check does not prove that frontend plugins compile; run the MiniStar build
+when plugin code or plugin-facing exports change.
+
+## Backend rules
+
+- Implement service behavior through `TcService` and a stable `serviceName`.
+- Register actions in `onInit` and declare concrete parameter validation.
+- Keep actions authenticated unless a public endpoint is deliberately reviewed.
+- Treat auth whitelists, action visibility, and socket exposure as security boundaries.
+- Perform final authorization in the service before reading or mutating data.
+- Use `call(ctx)` or explicit service calls for cross-service behavior.
+- Keep services focused; do not accumulate unrelated domains in one service.
+- Preserve cache invalidation, notifications, and room membership when data changes.
+- Use Typegoose models for persistence and avoid leaking protected model fields.
+- Prefer backward-compatible optional/default fields for persisted schema changes.
+- Add a migration under `server/scripts/migrations` when existing data needs rewriting.
+
+Group permissions are a cross-layer contract. When adding or renaming one,
+update both `client/shared/utils/role-helper.ts` and
+`server/packages/sdk/src/services/lib/role.ts`, then enforce it server-side.
+
+## Plugin rules
+
+- Use reverse-domain IDs such as `com.msgbyte.example` consistently.
+- Pure frontend plugins belong in `client/web/plugins/<id>`.
+- Backend/full-stack plugins belong in `server/plugins/<id>`.
+- Keep directory names, manifest names, service names, URLs, and keys aligned.
+- Register extensions through `@capital/common` or `@capital/component` APIs.
+- Use plugin-scoped request helpers; do not forward Tailchat credentials elsewhere.
+- Keep plugin translations local using the existing `localTrans` pattern.
+- Check manifests, entry registration, assets, and `requireRestart` behavior together.
+
+For full-stack plugins, verify the service/model implementation and the embedded
+web plugin. A frontend-only success is not proof that the complete plugin works.
+
+`client/web/src/plugin/builtin.ts` is the forced-install list.
+`client/web/registry.json` is the frontend store registry.
+`server/public/registry-be.json` is produced while installing server plugins.
+Change only the list that owns the requested behavior.
+
+## Contracts, generated files, and documentation
+
+Treat these as compatibility-sensitive public contracts:
+
+- shared types and SDK exports;
+- service action names, parameters, results, and visibility;
+- socket notification names and payloads;
+- plugin registration APIs and manifests;
+- persisted document shapes and permission identifiers.
+
+Check all known consumers before changing a contract. Prefer additive changes
+and explain unavoidable breaking changes.
+
+Generated artifacts must follow their source and owning command:
+
+- `client/web/tailchat.d.ts`: `pnpm --dir client/web plugins:declaration:generate`.
+- `server/openapi.json`: `pnpm --dir server gen:openapi`.
+- client core translations: `pnpm --dir client translation`.
+- server translations: `pnpm --dir server translation`.
+- website plugin lists: `pnpm --dir website gen:plugin-doc`.
+- server web-plugin assets/registry: the relevant `server` `plugin:install` flow.
+
+Review generated diffs and commit them only when their source contract changed.
+Do not hand-edit generated output into disagreement with its generator.
+
+Update `website/docs` when changing public commands, environment behavior,
+deployment, plugin APIs, OpenAPI behavior, or other user-facing contracts.
+Keep English source docs and existing Chinese translations consistent when both
+versions cover the changed material.
+
+## Verification by scope
+
+Run focused checks first, then broaden only when the change crosses boundaries.
+
+| Change scope | Minimum verification |
+| --- | --- |
+| Web or `client/shared` | `pnpm --dir client/web check:type` and focused `pnpm --dir client/web test --runInBand <test-path>` |
+| Web bundling/dependencies/plugin host | Above plus `pnpm --dir client/web build` |
+| Server service/model/plugin | `pnpm --dir server check:type` and focused `pnpm --dir server test --runInBand <test-path>` |
+| Server SDK | `pnpm --filter tailchat-server-sdk build` plus a relevant server consumer check |
+| Shared published types | `pnpm --filter tailchat-types build` plus relevant client/server checks |
+| Frontend plugin | Relevant Jest test and `pnpm --dir client/web plugins:all` |
+| Full-stack plugin | Server checks plus that plugin's `build:web` script and manifest review |
+| Admin | `pnpm build:admin` |
+| Website | `pnpm --dir website build` |
+| Cross-layer TypeScript | Focused checks plus root `pnpm check:type` |
+
+Server integration tests may require MongoDB and other configured services.
+State what was available rather than silently skipping or misreporting them.
+
+The root type check covers the core web and server projects, not every package,
+plugin web bundle, native shell, admin build, or documentation build. The root
+`pnpm build` is a packaging-level check; use it when the task affects packaging
+or crosses those boundaries, not for every small edit.
+
+Never claim a check passed unless it completed successfully. When a check fails,
+separate a new regression from a reproduced baseline failure or environment
+blocker and include the relevant error summary.
+
+Before handoff, run:
+
+```bash
+git diff --check
+git status --short --branch --untracked-files=all
+```
+
+## Git and delivery
+
+Do not commit, push, create a release, or open a pull request unless the task
+requests it. If asked, keep commits narrowly scoped and stage only intended files.
+
+Use Angular/Conventional Commits style for commits and pull-request titles:
+
+```text
+<type>(<scope>): <summary>
+fix(chat): adjust TTS popup spacing
+feat(image): add prompt presets
+```
+
+Use a lowercase type such as `fix`, `feat`, `chore`, `refactor`, `test`, `docs`,
+`build`, `ci`, `perf`, or `revert`. Use a concise lowercase scope when clear.
+Keep the summary short and imperative, with no trailing period.
+
+When creating a pull request, do not add a body unless explicitly requested.
+Final handoff should summarize changed files, verification performed, remaining
+failures or risks, and whether any generated or documentation updates were needed.