AGENTS.md git:20261007.a64593dA

Immutable. This exact content never changes and is served at /api/v1/blob/8f47b02fe92d730c.

# AGENTS.md

`dsh-agent-plugins-market` is the DeepSeek Harness plugin that installs Claude Code / Codex / Cursor / Kimi marketplace suites in place — zero conversion, zero file copying — and injects skills, MCP servers, hooks, commands, agents, and LSP servers into dsh sessions at runtime. Domain vocabulary lives in [CONTEXT.md](CONTEXT.md) (source, dialect, suite, surface, install state); use those terms exactly. Human onboarding and PR flow live in [CONTRIBUTING.md](CONTRIBUTING.md) — do not restate them here.

## Repository layout

```
index.ts        public installation entry: re-exports the bundle package. The published package name and
                artifact are unchanged; the workspace packages stay private.
packages/       eight private workspace packages consumed by that one artifact:
  market-bundle/       composition root and HTTP surface: src/index.ts (plugin entry), routes*.ts,
                       runtime-adapters.ts, application/, platform/
  market-catalog/      pure source scanning (scanning/) and the catalog use cases (application/)
  market-contracts/    stateless shared records: contracts/, model/, ports/, host/, redaction.ts —
                       imports nothing outside this package and uses no Node APIs
  market-runtime/      session selection and harness effects: runtime/ (core, surfaces, panels, agents,
                       host), application/, adapter-contracts.ts, catalog-port.ts, extension-service.ts
  market-mcp/          MCP configuration, the self-built bridge, mounts, tools and status
                       (application/, runtime/)
  market-lsp/          LSP configuration, mounts, provider lifecycle and status (application/, runtime/)
  market-translation/  translation engine, provider chain and translators (application/, runtime/)
  market-ui/           Web market page: src/index.ts, api.ts, locales.ts and i18n.ts, features/,
                       workspace/, ui/
schemas/        the layout specification library: vendored 1.0.0/ and 1.1.0/ agent-plugins schemas, one
                reference contract directory per dialect (plugin/marketplace schema + spec.md), and this
                manager's own com.deepseek.harness/ namespace — see schemas/README.md
tests/          vitest suites for the whole workspace; fixtures under tests/fixtures
docs/           user/, reference/, developer/{decisions,design,discussion,release,upstream-proposal}/, scratch/ — see docs/AGENTS.md
docs-site/      Astro docs site
scripts/        build and verification helpers: client banner, lifecycle verification, host-alignment
                and reuse gates, compatibility report, fixture updates, git-hook setup
```

## Commands

```sh
pnpm run typecheck           # the four TypeScript projects: server, client and both test projects
pnpm run lint                # eslint index.ts packages tests
pnpm run check:quick         # typecheck + lint — also runs before test and build
pnpm run format:check        # prettier — tracked text except the paths in .prettierignore
pnpm run test                # vitest run (full suite)
pnpm run test:contract       # routes + market contracts only
pnpm run check:architecture  # dependency-cruiser over the workspace packages
pnpm run check:reuse         # reuse ledger vs published host exports
pnpm run check:refactor      # check:quick + format:check + test:contract + architecture + reuse
pnpm run build               # tsc emits lib/, tsdown bundles client/
```

`check:quick` is the cheap half of the gate and runs on its own: `pretest` and `prebuild` invoke it, so a type or lint error surfaces the moment someone tests or builds rather than at review. The pre-commit hook runs it plus `format:check` and the host-alignment check — `git commit --no-verify` bypasses all three deliberately.

`check:refactor` is the standing local gate; `npm-publish.yml` reruns it plus `pnpm run test` on a release tag, so a green full suite before push is enough locally. Prettier covers files eslint does not, except the paths in [.prettierignore](.prettierignore) — run `format:check` after writing docs or HTML before claiming a green tree.

## Conventions

- **Reuse the host's own capability before building one.** A setting, a persisted store, a timer, a browser-side store, a config card, a listing API — when the harness already provides it, use the harness's. A local implementation needs a stated reason the host's does not fit, recorded as an `## Alternatives considered` entry in the change's Agent Note or ADR. Verify the **published package**, never the checkout: `npm view <pkg>@<baseline> dist.tarball`, then inspect that tarball's `files`/`exports` — a package present in the harness monorepo is not necessarily published, and one that publishes only `lib/*.js` plus `.d.ts` has no importable `src/`. Declare whatever is imported by the peer-vs-dependency rule in [the plugin development standard](docs/reference/dsh-plugin-development-standard.md) §2.1, and clear `pnpm run check:host-alignment`. Worked examples, and the deviations that survived a deliberate look, are in the [settings-and-card note](.agents/notes/implemented/architecture/2026-09-13-settings-and-card-ride-the-host.md).
- **Non-trivial changes include an Agent Note** in the same PR — a decision a maintainer may reasonably revisit is recorded under [.agents/notes/](.agents/notes/README.md) (proposed/implemented/rejected by class), and a new note triggers a supersession check of active notes on the same decision. Mechanical or local edits are exempt.
- **Commit types drive releases.** `feat:`/`fix:` in conventional-commit subjects are parsed by release-please into the next version and the changelog; a misclassified subject ships a wrong version. Scope the subject to the surface (`feat(mcp):`, `fix(lsp-status):`) and keep the body carrying the rationale.
- **Releases are workflow-owned.** release-please (embedded in `.github/workflows/npm-publish.yml`) opens the Release PR against `main`; merging it auto-tags, auto-creates the GitHub Release, and auto-publishes npm. Follow [docs/developer/release/release-process.md](docs/developer/release/release-process.md); the runbook's one hard rule: any remote write (`git push`, `git tag`, `npm publish`) requires user confirmation first.
- **Bilingual is part of the change.** User-visible strings go through `packages/market-ui/src/locales.ts` with paired zh/en keys; user-facing docs ship `README.md` and `README.zh.md` as one edit. A surface that renders English-only text is an incomplete change.
- **Validation fails closed.** A malformed manifest, `mcp.json` server, or `lspServers` declaration is diagnosed and skipped (or drops to an empty table), never silently half-mounted; suite data flows into `SourceOverview.scanNotes` and the status panels instead of disappearing. Follow the existing strategy-chain and status-builder patterns in `packages/market-catalog/src/` and `packages/market-runtime/src/`.
- **Docs accompany code.** A behavior change to config keys, defaults, routes, error codes, or schemas updates README(s), the affected `docs/` page, and JSDoc in the same PR. Architecture decisions get an ADR under `docs/developer/decisions/`.
- **Runtime owns effects; catalog stays pure.** Keep filesystem, process, and harness-context access in `packages/market-runtime/src/` and each adapter's `runtime/` folder; `packages/market-catalog/src/scanning/` resolvers stay testable pure functions. `check:architecture` enforces the boundaries, and the package dependency rules are recorded in [the domain workspace refactor](docs/developer/design/domain-workspace-refactor.md).
- **New dependencies are justified in the PR body** and land in `pnpm-lock.yaml` (`--frozen-lockfile` is the CI contract).

## Editing these instructions

Repository instructions live in the `AGENTS.md` files this tree ships ([docs/](docs/AGENTS.md), [.agents/notes/](.agents/notes/AGENTS.md)) plus the gitignored `AGENTS.local.md`; edit each rule in the file that owns it rather than duplicating it here. Keep each rule self-contained and link rationale instead of restating it.

The `dsh-workflow:begin`/`end` block below is generated by the `dsh-workflow` plugin (its `init-routing` command); re-running it rewrites the block in place and leaves the rest of this file untouched. Do not hand-edit inside the markers — the skills it routes to live in the plugin repositories (`agent-plugins`, `zealwon-plugins`), and the local `.agents/skills/market-*` skills are the repository-specific counterparts.

<!-- dsh-workflow:begin -->

## Skill routing

Route these duties through the dsh-workflow skills rather than ad-hoc practice.

| Before you…                                                                | Use the skill            |
| -------------------------------------------------------------------------- | ------------------------ |
| Push, mark ready for review, or claim checks pass                          | dsh-pre-push-checks      |
| Write or review prose, comments, README/JSDoc contracts, CLI or UI strings | dsh-prose-standard       |
| Audit text that reads like a reasoning transcript                          | dsh-trim-cot-leakage     |
| Add, restructure, review, or audit documentation                           | dsh-doc                  |
| Record or reclassify rationale, decisions, or postmortems                  | dsh-archive-agent-notes  |
| Update either side of a bilingual pair                                     | dsh-translate-docs       |
| Review a pull request                                                      | dsh-code-review          |
| Diagnose flaky or nondeterministic tests                                   | dsh-ci-test-reliability  |
| Look for redundancy, dead code, or over-built surfaces                     | dsh-find-simplifications |
| Land dependent pull requests as a stack                                    | dsh-merging-stacked-prs  |
| Investigate a performance regression                                       | dsh-speed-up-perf        |
| Attach a GUI demonstration to a pull request                               | record-browser-gif       |

## Placement

- Bug write-ups go to postmortems, rationale to Agent Notes, procedures to cookbooks, type definitions to source, package contracts to package READMEs, and standing orders to this file.
- Skills hold reusable workflows and specialized decision standards. Product and runtime contracts belong in docs or source.

<!-- dsh-workflow:end -->