Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(dsh): package version-specific usage documentation

tt-a1ia962390c4b83
diff --git a/integrations/deepseek-harness/CHANGELOG.md b/integrations/deepseek-harness/CHANGELOG.md
index 4d86ad9f..f2661237 100644
--- a/integrations/deepseek-harness/CHANGELOG.md
+++ b/integrations/deepseek-harness/CHANGELOG.md
@@ -1,13 +1,15 @@
# DSH adapter changelog
-## 1.0.0 — pending publication
+For current publication status, see the [repository integration README](https://github.com/tt-a1i/archify/tree/main/integrations/deepseek-harness).
+
+## 1.0.0
- First stable adapter contract for the exact tested host `@deepseek-ai/[email protected]`; the host remains a developer preview. Other host versions are not covered by this release claim.
- Bundles Archify 3.0.1 from stable commit `7158026e852f3aa6578c741e673b46d7878c92c1`, including the installation fix after the Archify v3.0.1 tag. Archify and adapter versions are independent.
- Preserves the Skill-only activation contract: one `archify-plugin` provider, no native tools, dependencies, install hooks, telemetry, or automatic updates.
- The release gate covers clean installation and published plugin 0.1.0 → 1.0.0 upgrade, discovery/loading, workspace rendering, and uninstall on Linux, macOS, and Windows. Full example-rewriting smoke runs outside the pnpm store.
- Archify 3.x changes the Viewer and authoring/delivery flow; existing schema-v1 input remains supported. See [Archify 3.0 upgrade notes](https://github.com/tt-a1i/archify/blob/v3.0.1/CHANGELOG.md#upgrading-from-2x). Existing HTML keeps its embedded Viewer.
-- The prepared 0.2.0 adapter was never published; 1.0.0 supersedes that candidate. Public installation remains 0.1.0 until this release is published and verified.
+- The prepared 0.2.0 adapter was never published; 1.0.0 supersedes that candidate.
## 0.1.0 — 2026-08-14
diff --git a/integrations/deepseek-harness/PACKAGE_README.md b/integrations/deepseek-harness/PACKAGE_README.md
new file mode 100644
index 00000000..2827de08
--- /dev/null
+++ b/integrations/deepseek-harness/PACKAGE_README.md
@@ -0,0 +1,48 @@
+# `@tt-a1i/archify-dsh` 1.0.0
+
+Community DeepSeek Harness integration for [Archify](https://github.com/tt-a1i/archify). This is **not** an official DeepSeek product and does not imply DeepSeek endorsement.
+
+This package bundles **Archify 3.0.1** from stable commit `7158026e852f3aa6578c741e673b46d7878c92c1`, including the installation fix after the `v3.0.1` tag. Both bundled version manifests declare 3.0.1. Adapter and Archify versions are independent.
+
+The 1.0 adapter contract covers the exact tested developer-preview host **`@deepseek-ai/[email protected]`** and Node.js **`^22.19.0 || >=24.0.0`**. It does not make the host stable or guarantee compatibility with other DSH versions. The release gate exercises clean installation and plugin 0.1.0 → 1.0.0 upgrade on Linux, macOS, and Windows using Node 22.
+
+## Install or upgrade
+
+After this version is available in the npm registry, install the exact version in each profile that uses Archify:
+
+```bash
+dsh plugin --profile web add @tt-a1i/[email protected]
+```
+
+The same command upgrades an existing plugin. Update the DSH host separately to the supported version first; the older `0.1.0-rc.6` host is not a supported 1.0 target. Updating DSH itself or the Archify repository does not update an installed plugin. Do not install from Git source: the repository root is not a DSH package.
+
+For an npm download problem, an integrity-verified tarball can be installed with `dsh plugin --profile web add /absolute/path/to/package.tgz`. See the [changelog](CHANGELOG.md) for the bundled Archify changes and the [repository integration README](https://github.com/tt-a1i/archify/tree/main/integrations/deepseek-harness) for publication status.
+
+## Invoke
+
+Ask DSH to load Archify by name:
+
+```text
+Use the archify skill to map this repository's runtime architecture.
+Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
+Put supporting detail in cards instead of adding more edges.
+After delivery, return the exact workspace paths of the specification JSON and the HTML artifact.
+```
+
+Archify uses DSH's ordinary Skill, shell, and filesystem paths. Generated files do not automatically appear in the Web Produced Files strip; ask for their **exact workspace paths** and open them from the workspace.
+
+## Uninstall
+
+```bash
+dsh plugin --profile web remove @tt-a1i/archify-dsh
+```
+
+The standard plugin command removes the adapter dependency and bundle layer. The base profile remains usable.
+
+## Activation and scope
+
+The bundle mounts one filesystem Skill provider named `archify-plugin`. Its `cordis.patch.yml` contains a `!!js` expression evaluated by the DSH host outside the agent sandbox. The expression uses Node's built-in `path` and `module` helpers to locate this installed package's `skills` directory; it does not fetch data, read credentials, spawn processes, or register another permission path. Review patch changes as host-process code.
+
+The adapter adds no native tools, custom Web client, telemetry, credentials handling, network client, background service, dependencies, or install hooks. The bundled Skill has an optional notification-only stable Archify update checker and bounded network access for authored remote brand assets. It never upgrades this plugin automatically.
+
+`release.json` records the immutable Skill source and exact acceptance host. Reproduce this version from its adapter tag `archify-dsh-v1.0.0` once published, using the committed pack script; use the recorded source rather than a moving branch.
diff --git a/integrations/deepseek-harness/README.md b/integrations/deepseek-harness/README.md
index 298c03fa..1aea73be 100644
--- a/integrations/deepseek-harness/README.md
+++ b/integrations/deepseek-harness/README.md
@@ -40,7 +40,7 @@ The bundle's `cordis.patch.yml` contains a `!!js` expression that DSH evaluates
Every Archify release records a sync or deferral decision in the [DSH synchronization checklist](../../CONTRIBUTING.md#release-checklist-dsh-synchronization). Plugin and Archify versions are independent.
-On a release branch, bump `package.json`, update `release.json` with the full source commit and matching Skill/DSH versions, and prepare the package README. The pack command reads adapter files and release metadata from the current adapter Git HEAD blob: commit those changes before packing; working-tree edits are not package inputs. Run:
+On a release branch, bump `package.json`, update `release.json` with the full source commit and matching Skill/DSH versions, and prepare `PACKAGE_README.md`, which is staged as the npm package’s `README.md`. This repository README tracks publication status separately. The pack command reads adapter files and release metadata from the current adapter Git HEAD blob: commit those changes before packing; working-tree edits are not package inputs. Run:
```bash
node --test integrations/deepseek-harness/test/*.test.mjs
diff --git a/integrations/deepseek-harness/scripts/release-source.mjs b/integrations/deepseek-harness/scripts/release-source.mjs
index ac1595d5..184c742d 100644
--- a/integrations/deepseek-harness/scripts/release-source.mjs
+++ b/integrations/deepseek-harness/scripts/release-source.mjs
@@ -7,7 +7,7 @@ import { spawnCliSync } from './resolve-cli.mjs';
export const integrationRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
export const repoRoot = path.resolve(integrationRoot, '..', '..');
const adapterPrefix = 'integrations/deepseek-harness/';
-const requiredAdapterFiles = ['package.json', 'release.json', 'cordis.patch.yml', 'README.md', 'CHANGELOG.md', 'lib/index.js'];
+const requiredAdapterFiles = ['package.json', 'release.json', 'cordis.patch.yml', 'PACKAGE_README.md', 'CHANGELOG.md', 'lib/index.js'];
function readGit(args) {
const result = spawnCliSync('git', args, { cwd: repoRoot, encoding: null, maxBuffer: 128 * 1024 * 1024 });
@@ -52,7 +52,9 @@ export const release = JSON.parse(adapterFiles.get('release.json').content.toStr
export function stageAdapter(destination) {
for (const [relative, entry] of adapterFiles) {
- const target = path.join(destination, ...relative.split('/'));
+ // The repository README tracks publication status; npm needs version-specific usage.
+ const packageRelative = relative === 'PACKAGE_README.md' ? 'README.md' : relative;
+ const target = path.join(destination, ...packageRelative.split('/'));
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, entry.content, { mode: entry.mode === '100755' ? 0o755 : 0o644 });
}
diff --git a/integrations/deepseek-harness/test/adapter-staging.test.mjs b/integrations/deepseek-harness/test/adapter-staging.test.mjs
index c5359a8e..c5e26960 100644
--- a/integrations/deepseek-harness/test/adapter-staging.test.mjs
+++ b/integrations/deepseek-harness/test/adapter-staging.test.mjs
@@ -155,6 +155,7 @@ test('pack stages adapter inputs from the fixture HEAD despite dirty and untrack
fs.writeFileSync(releasePath, `${JSON.stringify(release, null, 2)}\n`);
fs.appendFileSync(adapterPath(checkout, 'cordis.patch.yml'), `\n# ${dirtyMarker}\n`);
fs.appendFileSync(adapterPath(checkout, 'README.md'), `\n${dirtyMarker}\n`);
+ fs.appendFileSync(adapterPath(checkout, 'PACKAGE_README.md'), `\n${dirtyMarker}\n`);
fs.writeFileSync(adapterPath(checkout, 'lib/index.js'), `// ${dirtyMarker}\n`);
fs.writeFileSync(adapterPath(checkout, 'lib/untracked-dirty.mjs'), dirtyMarker);
@@ -165,14 +166,15 @@ test('pack stages adapter inputs from the fixture HEAD despite dirty and untrack
assert.equal(fs.existsSync(out), true);
const packageRoot = unpack(out, root);
- for (const relative of ['package.json', 'release.json', 'cordis.patch.yml', 'README.md', 'lib/index.js']) {
+ for (const relative of ['package.json', 'release.json', 'cordis.patch.yml', 'README.md', 'CHANGELOG.md', 'lib/index.js']) {
assert.deepEqual(
fs.readFileSync(path.join(packageRoot, ...relative.split('/'))),
- headBlob(checkout, head, relative),
+ headBlob(checkout, head, relative === 'README.md' ? 'PACKAGE_README.md' : relative),
`packed adapter input differs from fixture HEAD: ${relative}`,
);
}
assert.equal(fs.existsSync(path.join(packageRoot, 'lib', 'untracked-dirty.mjs')), false);
+ assert.equal(fs.existsSync(path.join(packageRoot, 'PACKAGE_README.md')), false);
const packedText = fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')
+ fs.readFileSync(path.join(packageRoot, 'release.json'), 'utf8')
+ fs.readFileSync(path.join(packageRoot, 'cordis.patch.yml'), 'utf8')
diff --git a/integrations/deepseek-harness/test/docs-contract.test.mjs b/integrations/deepseek-harness/test/docs-contract.test.mjs
index 5bf763e5..10e5cbc6 100644
--- a/integrations/deepseek-harness/test/docs-contract.test.mjs
+++ b/integrations/deepseek-harness/test/docs-contract.test.mjs
@@ -115,3 +115,15 @@ test('Skills CLI, Cursor, Codex, Claude Code, OpenCode, and Raven remain the def
const quickStartIndex = english.indexOf('## Quick start');
assert.ok(dshEnglishIndex > quickStartIndex, 'DSH docs must not precede the default quick start');
});
+
+test('npm README describes the packaged version independently of publication status', () => {
+ const packaged = read('integrations/deepseek-harness/PACKAGE_README.md');
+ assert.ok(packaged.includes(`@tt-a1i/archify-dsh@${candidate.adapterVersion}`));
+ assert.ok(packaged.includes(`Archify ${candidate.skillVersion}`));
+ assert.ok(packaged.includes(`@deepseek-ai/dsh@${candidate.dshVersion}`));
+ assert.ok(packaged.includes(candidate.sourceCommit));
+ assert.ok(packaged.includes(manifest.engines.node));
+ assert.doesNotMatch(packaged, /currently published npm package|not published or available as an npm install yet/);
+ assert.match(packaged, /After this version is available in the npm registry/);
+ assert.match(packaged, /outside the agent sandbox/);
+});