diff --git a/apps/ctl/README.md b/apps/ctl/README.md
index 8710ecaf1..af91375ed 100644
--- a/apps/ctl/README.md
+++ b/apps/ctl/README.md
@@ -5,7 +5,8 @@ OWOX Data Marts Control CLI.
 `owox` runs and manages a local or self-managed OWOX Data Marts runtime.
 `owox-ctl` controls an existing OWOX Data Marts instance through the HTTP API.
 
-The full user documentation lives in [docs/api/owox-ctl.md](../../docs/api/owox-ctl.md).
+The full user documentation lives in
+[owox-ctl API documentation](https://docs.owox.com/docs/api/owox-ctl/).
 
 ## Install
 
diff --git a/apps/ctl/package.json b/apps/ctl/package.json
index 932f7157e..f70c67e33 100644
--- a/apps/ctl/package.json
+++ b/apps/ctl/package.json
@@ -32,6 +32,7 @@
     "node": ">=22.16.0"
   },
   "files": [
+    "./README.md",
     "./bin",
     "./dist/**/*.d.ts",
     "./dist/**/*.js",
diff --git a/apps/ctl/src/package-readme.test.ts b/apps/ctl/src/package-readme.test.ts
new file mode 100644
index 000000000..cf3a0d9ac
--- /dev/null
+++ b/apps/ctl/src/package-readme.test.ts
@@ -0,0 +1,11 @@
+import { readFileSync } from 'node:fs';
+
+describe('package README', () => {
+  const readme = readFileSync(new URL('../README.md', import.meta.url), 'utf8');
+
+  it('links to the full CLI documentation with a stable package-safe URL', () => {
+    expect(readme).toContain('https://docs.owox.com/docs/api/owox-ctl/');
+    expect(readme).not.toContain('../../docs/api/owox-ctl.md');
+    expect(readme).not.toContain('github.com/OWOX/owox-data-marts/blob/main/docs');
+  });
+});
diff --git a/packages/api-client/README.md b/packages/api-client/README.md
new file mode 100644
index 000000000..3ae9d7525
--- /dev/null
+++ b/packages/api-client/README.md
@@ -0,0 +1,16 @@
+# @owox/api-client
+
+TypeScript/JavaScript client for calling the OWOX Data Marts API from custom
+scripts, internal tools, automation, and local agent workflows.
+
+## Install
+
+```bash
+npm install @owox/api-client
+```
+
+## Documentation
+
+- [@owox/api-client guide](https://docs.owox.com/docs/api/api-client/)
+- [API Keys](https://docs.owox.com/docs/api/api-keys/)
+- [OpenAPI and Swagger UI](https://docs.owox.com/docs/api/openapi/)
diff --git a/packages/api-client/package.json b/packages/api-client/package.json
index 0b1704ebd..90824a674 100644
--- a/packages/api-client/package.json
+++ b/packages/api-client/package.json
@@ -44,6 +44,7 @@
     "ts-jest": "^29.4.6"
   },
   "files": [
+    "README.md",
     "dist"
   ],
   "exports": {
diff --git a/packages/api-client/src/package-readme.test.ts b/packages/api-client/src/package-readme.test.ts
new file mode 100644
index 000000000..24f15740a
--- /dev/null
+++ b/packages/api-client/src/package-readme.test.ts
@@ -0,0 +1,26 @@
+import { existsSync, readFileSync } from 'node:fs';
+
+describe('package README', () => {
+  const readmeUrl = new URL('../README.md', import.meta.url);
+
+  it('provides npm users with install and package-safe documentation links', () => {
+    if (!existsSync(readmeUrl)) {
+      throw new Error('packages/api-client/README.md must exist for npm package publishing');
+    }
+
+    const readme = readFileSync(readmeUrl, 'utf8');
+
+    expect(readme).toContain('# @owox/api-client');
+    expect(readme).toContain('npm install @owox/api-client');
+    expect(readme).toContain('https://docs.owox.com/docs/api/api-client/');
+    expect(readme).toContain('https://docs.owox.com/docs/api/api-keys/');
+    expect(readme).toContain('https://docs.owox.com/docs/api/openapi/');
+    expect(readme).not.toContain('github.com/OWOX/owox-data-marts/blob/main/docs');
+    expect(readme).not.toContain('new OWOXApiClient');
+    expect(readme).not.toContain('## Basic usage');
+    expect(readme).not.toContain('## Error handling');
+    expect(readme).not.toContain('./api-keys/');
+    expect(readme).not.toContain('./owox-ctl/');
+    expect(readme).not.toContain('./openapi/');
+  });
+});