PSkinnerTech · PSkinnerTech · May 21, 2026 · May 21, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,8 @@
 # Changelog
 
-## Unreleased - 2026-05-18
+## Unreleased
+
+## 0.3.0 - 2026-05-21
 
 - Added Phase D.2 deterministic rule-depth findings for duplicate content clusters, structured-data visible-content mismatches, and entity clarity gaps.
 - Added Phase D.1 render parity findings for explicitly rendered audits, including changed title, description, canonical, missing rendered heading/content, and structured-data loss checks.
@@ -24,6 +26,8 @@
 - Kept Astro framework coverage limited to detection and static-output audits until an explicit integration-generated route artifact is available.
 - Hardened repo command guardrails so restricted mode blocks local build and preview command execution before spawning, and explicit preview options take precedence over static output so callers can audit live preview servers even when a stale `dist` directory exists.
 - Polished CLI Markdown reports with repo Markdown golden coverage and aligned the skill report template, README, PRD, and skill guidance around the same priorities, dimensions, developer tasks, repository evidence, imported measurements, evidence gaps, and sources structure.
+- Added a root package `private: true` guardrail to prevent accidental root package publishing.
+- Added CLI package metadata, package-facing README, and MIT license files to improve packed package readiness.
 - Expanded the test suite to cover repo detection, static route discovery, repo audit orchestration, preview lifecycle behavior, CLI validation, report/schema compatibility, packaging, and release-gate hardening.
 
 ## 0.2.0 - 2026-05-18

diff --git a/docs/prd-deterministic-audit-cli.md b/docs/prd-deterministic-audit-cli.md
@@ -3,7 +3,7 @@
 Status: Current implementation baseline plus developer repo-audit roadmap
 Date: 2026-05-18
 Repository: openclaw-geo-seo-audit-skill
-Current CLI package: openclaw-geo-seo-audit@0.2.0; main includes unreleased repo audit mode
+Current CLI package: openclaw-geo-seo-audit@0.3.0 release candidate
 Primary users: technical SEOs, growth teams, content strategists, frontend engineers, agency auditors, and AI agents running OpenClaw skills
 
 ## 1. Summary
@@ -19,7 +19,7 @@ The production direction remains a deterministic SEO/GEO readiness auditor. Actu
 
 ### Current baseline
 
-As of `openclaw-geo-seo-audit@0.2.0` plus the merged repo-audit branch, the repository contains a working deterministic CLI and OpenClaw skill wrapper. The CLI can audit local HTML, live URLs, URL lists, sitemap-seeded crawls, bounded same-origin crawls, static output repositories, and explicit preview-server repositories. It emits JSON and Markdown, imports supplied ranking/performance evidence, evaluates deterministic page and site rules, includes repo evidence for source-repository audits, and includes restricted-mode guardrails for untrusted targets.
+As of the `openclaw-geo-seo-audit@0.3.0` release candidate, the repository contains a working deterministic CLI and OpenClaw skill wrapper. The CLI can audit local HTML, live URLs, URL lists, sitemap-seeded crawls, bounded same-origin crawls, static output repositories, and explicit preview-server repositories. It emits JSON and Markdown, imports supplied ranking/performance evidence, evaluates deterministic page and site rules, includes repo evidence for source-repository audits, and includes restricted-mode guardrails for untrusted targets.
 
 The latest completed product target is developer-focused repo audit completion: repository audits now support explicit build commands, route lists, repo config, CI threshold failures, and deterministic source-level findings without overclaiming rankings.
 
@@ -30,7 +30,7 @@ The current repository contains a working deterministic CLI, an OpenClaw skill w
 Current remaining gaps:
 
 - The CLI can audit static output and explicit preview-server repositories with explicit build commands, route-list parity, and repo config files; remaining repo-audit work focuses on broader framework fixture coverage and deeper deterministic source-level findings.
-- Release documentation and changelog entries must stay aligned with the implemented `0.2.0` baseline plus unreleased repo-audit work before publishing the next package version.
+- Release documentation and changelog entries must stay aligned with the implemented `0.3.0` release candidate before publishing the next package version.
 - Some rule IDs exist in the taxonomy before full trigger coverage, especially deeper entity clarity, hidden text risk, duplicate content clusters, and structured-data visible-content mismatch.
 - Ranking and GEO visibility measurement still depends on supplied exports. API-backed Search Console, SERP provider, and AI-answer probes are future integrations.
 - The product needs developer-optimized repo audit workflows that can safely build or preview common web apps, crawl generated output, connect source-level evidence to rendered output, and produce CI-friendly failure semantics.
@@ -321,7 +321,7 @@ Top-level shape:
 ```json
 {
   "schemaVersion": "1.0.0",
-  "toolVersion": "0.2.0",
+  "toolVersion": "0.3.0",
   "run": {},
   "site": {},
   "pages": [],
@@ -915,7 +915,7 @@ Resolved for developer repo audit completion:
 
 ## 22. Release Stabilization And v1.5 Readiness Checklist
 
-Before publishing or tagging `0.2.0`:
+Before publishing or tagging `0.3.0`:
 
 - Verify the PRD, README, skill wrapper, changelog, and release checklist describe the same shipped CLI baseline.
 - Run `npm ci`, `npm audit --omit=dev`, `npm test`, `npm run validate`, and `npm pack --dry-run --workspace packages/cli`.

diff --git a/docs/release-checklist.md b/docs/release-checklist.md
@@ -10,6 +10,7 @@ Before publishing:
 - Confirm `CHANGELOG.md` contains the package version being released.
 - Confirm `README.md` and `skill/geo-seo-audit/SKILL.md` describe readiness versus measured rankings accurately.
 - Confirm raw source corpus files remain repository assets and are not included in the CLI package dry run.
+- Confirm the root `package.json` has `private: true` so accidental root publishes are blocked.
 
 ## Verification
 
@@ -21,6 +22,7 @@ npm audit --omit=dev
 npm test
 npm run validate
 npm pack --dry-run --workspace packages/cli
+npm pack --dry-run --json
 ```
 
 For CI gating, run audits with a severity threshold:
@@ -40,9 +42,26 @@ The audit command returns exit code `2` when findings meet or exceed the configu
 ## Publish Dry Run
 
 - Confirm `npm pack --dry-run --workspace packages/cli` includes only intended package files.
+- Confirm `npm pack --dry-run` at the repository root is not used as a publish target; the root package is private and the publishable package is the CLI workspace.
 - Confirm optional Playwright support remains optional.
 - Confirm fixture/golden files remain repository test assets and are not shipped in the CLI package.
 
+## Packed CLI Smoke
+
+Pack and install the CLI workspace in a temporary project before publishing:
+
+```bash
+tmpdir="$(mktemp -d)"
+npm pack --workspace packages/cli --pack-destination "$tmpdir"
+mkdir "$tmpdir/install"
+cd "$tmpdir/install"
+npm init -y
+npm install --ignore-scripts "$tmpdir"/openclaw-geo-seo-audit-*.tgz
+npx openclaw-geo-seo-audit --version
+npx openclaw-geo-seo-audit --help
+npx openclaw-geo-seo-audit explain-rule indexability.noindex
+```
+
 ## Post-Merge Verification
 
 After merging release-stabilization work to `main`, run:
@@ -55,6 +74,7 @@ npm audit --omit=dev
 npm test
 npm run validate
 npm pack --dry-run --workspace packages/cli
+npm pack --dry-run --json
 git status --short --branch
 ```
 
@@ -63,7 +83,8 @@ Expected result:
 - Audit reports `found 0 vulnerabilities`.
 - Tests pass.
 - Validation reports `ok: true`.
-- Package dry run lists only intended CLI package files.
+- CLI package dry run lists only intended CLI package files.
+- Root pack dry run is treated as a private-root packaging sanity check, not a publish artifact.
 - Git status shows a clean `main` branch.
 
 ## GitHub Release Workflow

diff --git a/docs/superpowers/specs/2026-05-21-repo-audit-ci-ergonomics-design.md b/docs/superpowers/specs/2026-05-21-repo-audit-ci-ergonomics-design.md
@@ -0,0 +1,28 @@
+# Repo Audit CI Ergonomics And Task Surfaces
+
+Status: Draft scoping note, not approved implementation spec
+
+## Goal
+
+Make repo audits easier to consume in CI and developer workflows without changing the existing JSON schema incompatibly.
+
+## Candidate Deliverables
+
+- Compact summary.
+- GitHub annotations.
+- SARIF and JUnit emitters.
+- Normalized issue projection combining page findings and repo source findings.
+- Additive task/source mapping fields.
+- One additional framework fixture.
+
+## Constraints And Risks
+
+- Keep readiness versus measured visibility language honest.
+- Do not overfit SARIF or JUnit output to one CI provider.
+- Source line numbers are sparse.
+- Schema additions must be additive.
+- Keep repo source findings separate in normal Markdown reports.
+
+## Next Step
+
+Run a full Superpowers brainstorming/spec pass before implementation.
diff --git a/examples/golden/known-issues-summary.json b/examples/golden/known-issues-summary.json
@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "toolVersion": "0.2.0",
+  "toolVersion": "0.3.0",
   "run": {
     "target": "http://fixture.test/",
     "mode": "full",

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "openclaw-geo-seo-audit-skill",
   "version": "0.1.0",
-  "private": false,
+  "private": true,
   "type": "module",
   "workspaces": [
     "packages/*"

diff --git a/packages/cli/LICENSE b/packages/cli/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Skinner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the Software), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED AS IS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -0,0 +1,30 @@
+# openclaw-geo-seo-audit
+
+Deterministic GEO/SEO readiness audits for websites and source repositories.
+
+The CLI inspects crawlability, indexability, search appearance, structured data, content answerability, entity clarity, optional performance imports, and repository audit evidence. It reports readiness by default. Measured ranking or AI-answer visibility requires supplied Search Console, SERP, or AI-answer evidence; Lighthouse exports can add performance measurements.
+
+## Install
+
+```bash
+npm install -g openclaw-geo-seo-audit
+```
+
+Playwright is optional. Install it in projects where rendered page evidence is needed.
+
+## Usage
+
+```bash
+openclaw-geo-seo-audit --help
+openclaw-geo-seo-audit audit https://example.com --mode full --max-pages 25 --out audit.json --markdown audit.md
+openclaw-geo-seo-audit audit-repo ./site --static-dir dist --fail-on P1 --out repo-audit.json --markdown repo-audit.md
+openclaw-geo-seo-audit explain-rule indexability.noindex
+```
+
+Use `--security restricted` for untrusted live-site audits or hosted wrappers. Restricted mode applies guarded network and file access limits and disables local command execution.
+
+## Outputs
+
+The CLI emits versioned JSON and optional Markdown. Findings include stable rule IDs, severity, evidence paths, implementation-task guidance, and source citations where applicable.
+
+Readiness scores are not ranking guarantees. Treat scores and findings as deterministic implementation evidence, then combine them with measured visibility data when available.
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -1,13 +1,35 @@
 {
   "name": "openclaw-geo-seo-audit",
-  "version": "0.2.0",
+  "version": "0.3.0",
+  "description": "Deterministic GEO/SEO readiness audit CLI for websites and source repositories.",
   "private": false,
   "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PSkinnerTech/openclaw-geo-seo-audit-skill.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/PSkinnerTech/openclaw-geo-seo-audit-skill#readme",
+  "bugs": {
+    "url": "https://github.com/PSkinnerTech/openclaw-geo-seo-audit-skill/issues"
+  },
+  "keywords": [
+    "seo",
+    "geo",
+    "generative-engine-optimization",
+    "audit",
+    "cli",
+    "technical-seo",
+    "repository-audit"
+  ],
   "bin": {
     "openclaw-geo-seo-audit": "./src/index.mjs"
   },
   "files": [
     "src",
+    "README.md",
+    "LICENSE",
     "package.json"
   ],
   "scripts": {

diff --git a/packages/cli/src/audit.mjs b/packages/cli/src/audit.mjs
@@ -10,7 +10,7 @@ import { evaluateSite } from "./site-rule-engine.mjs";
 import { collectSnapshot } from "./snapshot.mjs";
 import { isHttpUrl } from "./url-utils.mjs";
 
-const toolVersion = "0.2.0";
+const toolVersion = "0.3.0";
 
 const readSourceMap = () => {
   const candidates = [

diff --git a/packages/cli/src/cli.mjs b/packages/cli/src/cli.mjs
@@ -8,7 +8,7 @@ import { detectRepo } from "./repo-detect.mjs";
 import { getRule } from "./rules.mjs";
 import { collectSnapshot } from "./snapshot.mjs";
 
-const version = "openclaw-geo-seo-audit 0.2.0";
+const version = "openclaw-geo-seo-audit 0.3.0";
 
 const help = `Usage: openclaw-geo-seo-audit <command> [options]
 

diff --git a/packages/cli/src/repo-audit.mjs b/packages/cli/src/repo-audit.mjs
@@ -7,7 +7,7 @@ import { analyzeFrameworkRouteManifests } from "./repo-manifests.mjs";
 import { runCommand, startPreview, stopPreview } from "./repo-process.mjs";
 import { discoverStaticRoutes } from "./repo-routes.mjs";
 
-const toolVersion = "0.2.0";
+const toolVersion = "0.3.0";
 
 const relativePath = (repoPath, targetPath) => {
   if (!targetPath) return null;

diff --git a/packages/cli/test/audit-output-schema.test.mjs b/packages/cli/test/audit-output-schema.test.mjs
@@ -5,7 +5,7 @@ import { validateAuditOutput } from "../src/audit-output-schema.mjs";
 test("accepts minimal valid audit output", () => {
   const result = validateAuditOutput({
     schemaVersion: "1.0.0",
-    toolVersion: "0.2.0",
+    toolVersion: "0.3.0",
     run: {},
     site: {},
     pages: [],
@@ -28,7 +28,7 @@ test("rejects missing top-level audit output fields", () => {
 test("rejects findings missing required fields", () => {
   const result = validateAuditOutput({
     schemaVersion: "1.0.0",
-    toolVersion: "0.2.0",
+    toolVersion: "0.3.0",
     run: {},
     site: {},
     pages: [],
@@ -45,7 +45,7 @@ test("rejects findings missing required fields", () => {
 test("accepts optional repo evidence section", () => {
   const audit = {
     schemaVersion: "1.0.0",
-    toolVersion: "0.2.0",
+    toolVersion: "0.3.0",
     run: {},
     site: {},
     pages: [],
@@ -67,7 +67,7 @@ test("accepts optional repo evidence section", () => {
 test("rejects optional repo evidence section when it is not an object", () => {
   const result = validateAuditOutput({
     schemaVersion: "1.0.0",
-    toolVersion: "0.2.0",
+    toolVersion: "0.3.0",
     run: {},
     site: {},
     pages: [],

diff --git a/packages/cli/test/audit.test.mjs b/packages/cli/test/audit.test.mjs
@@ -20,7 +20,7 @@ const withServer = async (handler, fn) => {
 test("returns minimal versioned audit output for a local HTML target", async () => {
   const audit = await runAudit({ target: "examples/fixture-site/index.html", crawl: { mode: "single", maxPages: 1, maxDepth: 0 } });
   assert.equal(audit.schemaVersion, "1.0.0");
-  assert.equal(audit.toolVersion, "0.2.0");
+  assert.equal(audit.toolVersion, "0.3.0");
   assert.match(audit.run.configHash, /^[a-f0-9]{64}$/);
   assert.deepEqual(audit.run.crawl, { mode: "single", maxPages: 1, maxDepth: 0 });
   assert.equal(audit.pages.length, 1);

diff --git a/packages/cli/test/cli.test.mjs b/packages/cli/test/cli.test.mjs
@@ -30,7 +30,7 @@ const freePort = async () =>
 test("prints version", async () => {
   const result = await capture(["--version"]);
   assert.equal(result.exitCode, 0);
-  assert.match(result.stdout, /openclaw-geo-seo-audit/);
+  assert.equal(result.stdout.trim(), "openclaw-geo-seo-audit 0.3.0");
 });
 
 test("prints help", async () => {

diff --git a/packages/cli/test/package.test.mjs b/packages/cli/test/package.test.mjs
@@ -17,4 +17,7 @@ test("packed CLI includes the source map used by audit output", async () => {
 
   assert.ok(files.includes("src/audit.mjs"));
   assert.ok(files.includes("src/source-map.json"));
+  assert.ok(files.includes("README.md"));
+  assert.ok(files.includes("LICENSE"));
+  assert.ok(files.includes("package.json"));
 });
diff --git a/packages/cli/test/report.test.mjs b/packages/cli/test/report.test.mjs
@@ -4,7 +4,7 @@ import { generateMarkdownReport } from "../src/report.mjs";
 
 const polishedAuditFixture = () => ({
   schemaVersion: "1.0.0",
-  toolVersion: "0.2.0",
+  toolVersion: "0.3.0",
   run: {
     target: "https://example.com",
     startedAt: "2026-05-20T10:00:00.000Z",
@@ -180,7 +180,7 @@ test("includes repository evidence when audit repo evidence exists", () => {
 test("includes repository build evidence when present", () => {
   const markdown = generateMarkdownReport({
     schemaVersion: "1.0.0",
-    toolVersion: "0.2.0",
+    toolVersion: "0.3.0",
     run: { id: "run", startedAt: "now", endedAt: "now", target: "repo", mode: "repo" },
     site: { notes: [] },
     pages: [],