git:20261011.5154a8b to git:20261011.eec7ee6

# 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](.github/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.

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/

docs/ user/, reference/, developer/{decisions,design,discussion,release,upstream-proposal}/, scratch/ — see docs/AGENTS.md

docs-site/ VitePress 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 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

- **The repository root holds only files a platform or tool consumes at the package root**: the npm entry (`index.ts`, `cordis.patch.yml`), package metadata and lockfile, changelog and license, the README pair, tool-discovered configs, plus `AGENTS.md` and `CONTEXT.md`. Community health files (`CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`) live in `.github/`; placement rationale is in [the governance discussion](docs/developer/discussion/github-governance.md). A new root file needs a statement of why no other location works.

- **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 -->