/web-publish

Deploy and manage the CODITECT Web Publishing Platform for: $ARGUMENTS

System Prompt

EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

IMMEDIATELY execute - no questions, no explanations first
ALWAYS show full output from script/tool execution
ALWAYS provide summary after execution completes

DO NOT:

Say "I don't need to take action" - you ALWAYS execute when invoked
Ask for confirmation unless requires_confirmation: true in frontmatter
Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

Arguments

$ARGUMENTS - Deployment Options

Argument	Description
`--init`	Initialize web publishing platform in current project
`--serve`	Launch the dev server (default if platform already exists)
`--manifest`	Regenerate publish.json manifest only
`--dashboard-data`	Regenerate project-dashboard-data.json + AI brief
`--check`	Run doc readiness check
`--status`	Show platform status (installed, dependencies, docs count)
`--port N`	Custom port (default: 5173)
`--no-open`	Don't open browser after launch

Default Behavior

If no arguments and platform is already deployed:

Regenerate manifest from current docs
Launch dev server on port 5173
Open browser

If no arguments and platform is NOT deployed:

Run --init flow

Usage

# Initialize platform in a new project
/web-publish --init

# Launch existing platform
/web-publish --serve

# Regenerate manifest after adding docs
/web-publish --manifest

# Regenerate dashboard data from TRACK files
/web-publish --dashboard-data

# Check documentation readiness
/web-publish --check

# Quick status
/web-publish --status

Execution Steps

Step 1: Detect Platform State

# Check if web publishing platform exists in current project
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)

# Look for platform markers
if [ -f "$PROJECT_ROOT/viewer.jsx" ] && [ -f "$PROJECT_ROOT/package.json" ]; then
    PLATFORM_STATE="deployed"
elif [ -d "$PROJECT_ROOT/tools/web-publishing-platform" ]; then
    PLATFORM_STATE="deployed-in-tools"
    PLATFORM_DIR="$PROJECT_ROOT/tools/web-publishing-platform"
else
    PLATFORM_STATE="not-deployed"
fi

Step 2: Route by Action

--init (or first-time detection):

# 1. Copy platform artifacts from coditect-core
CORE_WPP="$HOME/.coditect/tools/web-publishing-platform"

# Verify source exists
if [ ! -d "$CORE_WPP" ]; then
    echo "ERROR: Web Publishing Platform not found in coditect-core"
    echo "Expected: $CORE_WPP"
    exit 1
fi

# 2. Copy to project root (or specified directory)
TARGET_DIR="${PROJECT_ROOT}"
cp -r "$CORE_WPP/components" "$TARGET_DIR/"
cp -r "$CORE_WPP/dashboards" "$TARGET_DIR/"
cp -r "$CORE_WPP/scripts" "$TARGET_DIR/"
cp -r "$CORE_WPP/public" "$TARGET_DIR/"
cp "$CORE_WPP/viewer.jsx" "$TARGET_DIR/"
cp "$CORE_WPP/styles.css" "$TARGET_DIR/"
cp "$CORE_WPP/index.html" "$TARGET_DIR/"
cp "$CORE_WPP/vite.config.js" "$TARGET_DIR/"
cp "$CORE_WPP/package.json" "$TARGET_DIR/"

# 3. Install dependencies
cd "$TARGET_DIR"
npm install

# 4. Generate initial manifest
node scripts/generate-publish-manifest.js

# 5. Launch dev server
npm run dev

--serve (platform already deployed):

cd "$PLATFORM_DIR"

# Check for node_modules
if [ ! -d "node_modules" ]; then
    npm install
fi

# Check port availability
PORT=${CUSTOM_PORT:-5173}
if lsof -i :"$PORT" -P -n | grep LISTEN > /dev/null 2>&1; then
    echo "Port $PORT is already in use:"
    lsof -i :"$PORT" -P -n | grep LISTEN
    echo ""
    echo "Options:"
    echo "  1. Kill existing process: /web-publish --serve --port $((PORT+1))"
    echo "  2. Use different port: /web-publish --serve --port 5174"
    exit 1
fi

# Launch
npm run dev -- --port "$PORT"

--manifest:

cd "$PLATFORM_DIR"
node scripts/generate-publish-manifest.js
echo "Manifest regenerated: public/publish.json"

--dashboard-data:

cd "$PLATFORM_DIR"
node scripts/generate-project-dashboard-data.js
echo "Dashboard data regenerated:"
echo "  - public/project-dashboard-data.json"
echo "  - public/project-status-brief.md"

--check:

cd "$PLATFORM_DIR"
bash scripts/check-doc-readiness.sh

--status:

echo "=== Web Publishing Platform Status ==="
echo ""

if [ "$PLATFORM_STATE" = "not-deployed" ]; then
    echo "Status: NOT DEPLOYED"
    echo "Run: /web-publish --init"
    exit 0
fi

echo "Status: DEPLOYED"
echo "Location: $PLATFORM_DIR"

# Dependencies
if [ -d "$PLATFORM_DIR/node_modules" ]; then
    echo "Dependencies: Installed"
else
    echo "Dependencies: NOT INSTALLED (run: npm install)"
fi

# Document count
DOC_COUNT=$(find "$PLATFORM_DIR/../docs" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
echo "Documents: $DOC_COUNT markdown files"

# Dashboard count
DASH_COUNT=$(find "$PLATFORM_DIR/dashboards" -name "*.jsx" 2>/dev/null | wc -l | tr -d ' ')
echo "Dashboards: $DASH_COUNT JSX dashboards"

# Manifest
if [ -f "$PLATFORM_DIR/public/publish.json" ]; then
    MANIFEST_DOCS=$(python3 -c "import json; print(json.load(open('$PLATFORM_DIR/public/publish.json'))['total_documents'])" 2>/dev/null)
    echo "Manifest: $MANIFEST_DOCS documents indexed"
else
    echo "Manifest: NOT GENERATED (run: /web-publish --manifest)"
fi

# Server check
if lsof -i :5173 -P -n | grep LISTEN > /dev/null 2>&1; then
    echo "Server: RUNNING on port 5173"
else
    echo "Server: NOT RUNNING"
fi

Examples

Initialize in New Project

/web-publish --init
# Output:
# Copying platform artifacts from coditect-core...
#   7 components, 28 dashboards, 3 scripts
# Installing dependencies...
#   added 142 packages in 8s
# Generating manifest...
#   Generated publish.json: 45 documents across 8 categories
# Launching dev server...
#   VITE v7.x ready in 320ms
#   http://localhost:5173

Refresh After Adding Docs

/web-publish --manifest
# Output:
# Generated publish.json: 52 documents across 9 categories
#   Architecture: 8 (8 markdown)
#   Compliance: 4 (4 markdown)
#   ...

Check Readiness

/web-publish --check
# Output:
# === Documentation Readiness Check ===
# Total: 52 files
# With frontmatter: 48 (92%)
# Missing title: 2
# Missing summary: 4
# Grade: B (92%)

Architecture

┌──────────────────────────────────────────────────┐
│                 /web-publish                       │
│                                                    │
│  ┌────────────┐  ┌─────────────┐  ┌────────────┐ │
│  │   --init   │  │   --serve   │  │ --manifest  │ │
│  │  Copy from │  │  npm run    │  │ Regenerate  │ │
│  │  core, npm │  │  dev, port  │  │ publish.json│ │
│  │  install   │  │  management │  │             │ │
│  └─────┬──────┘  └─────┬───────┘  └──────┬─────┘ │
│        │               │                  │       │
│        ▼               ▼                  ▼       │
│  ┌──────────────────────────────────────────────┐ │
│  │     tools/web-publishing-platform/            │ │
│  │     (46 files: components, dashboards,        │ │
│  │      scripts, config, public assets)          │ │
│  └──────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

Resource	Path
Platform README	`tools/web-publishing-platform/README.md`
SDD	`tools/web-publishing-platform/docs/SOFTWARE-DESIGN-DOCUMENT.md`
TDD	`tools/web-publishing-platform/docs/TEST-DRIVEN-DEVELOPMENT.md`
ADR-197	`internal/architecture/adrs/ADR-197-*.md`
ADR-199	`internal/architecture/adrs/ADR-199-*.md`
`/serve`	`commands/serve.md` — Generic project server launcher
`/start-viewer`	`commands/start-viewer.md` — Component viewer launcher
Skill	`skills/web-publishing/SKILL.md`
Agent	`agents/web-publish.md`

Success Output

✅ COMMAND COMPLETE: /web-publish
Action: <init|serve|manifest|dashboard-data|check|status>
Platform: <deployed|not-deployed>
Documents: N indexed
Server: <running on port NNNN|not started>

Completion Checklist

Before marking complete:

Platform state detected correctly
Action executed successfully
Output displayed to user
No unhandled errors

Failure Indicators

This command has FAILED if:

Platform source not found in coditect-core
npm install fails
Manifest generation produces empty output
Dev server fails to start

When NOT to Use

Do NOT use when:

Working on coditect-core's own web-publishing-platform (use npm run dev directly)
Need simple static file serving (use /serve instead)
Only need component viewer (use /start-viewer instead)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip --init	Missing dependencies	Always initialize first
Ignore --check	Broken frontmatter	Check before publishing
Manual copy	Drift from canonical	Use --init for consistency

Principles

This command embodies:

#1 Recycle, Extend, Re-Use - Copies canonical artifacts from coditect-core
#2 Self-Provisioning - Auto-installs dependencies
#3 Complete Execution - Init + install + manifest + serve in one command

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Track: H.10.5 (Unified Web Publishing) ADR: ADR-197 Version: 1.0.0 Created: 2026-02-15

System Prompt​

Arguments​

$ARGUMENTS - Deployment Options​

Default Behavior​

Usage​

Execution Steps​

Step 1: Detect Platform State​

Step 2: Route by Action​

Examples​

Initialize in New Project​

Refresh After Adding Docs​

Check Readiness​

Architecture​

Related​

Success Output​

Completion Checklist​

Failure Indicators​

When NOT to Use​

Anti-Patterns (Avoid)​

Principles​