technical-seo

Standalone technical SEO tool workspace. It can be used through its CLI or as a Claude operator workspace.

What this is

A self-contained operator workspace that performs only:

• Crawlability, indexability, redirects, hreflang
• Site structure and internal linking
• Schema markup validation
• Core Web Vitals and PageSpeed
• Security headers, mobile-first, image tech
• llms.txt and AI-crawler readiness
• Single-page and full-site technical audits

What you get

The workspace exposes 5 high-level orchestrator commands to keep the surface beginner-friendly. Per-module audits are still available, but as a flag (--only <module>) on the orchestrator, or as internal commands under /smartspec:_internal:<module> for advanced workflows.

Orchestrators (5 visible commands)

| Command | Purpose | |---|---| | /smartspec:status | system overview, doctor health, last audit | | /smartspec:audit <client> [--only <m,...>] | full-site audit or single-module slice | | /smartspec:page <client> <url> | single-page deep audit | | /smartspec:daily <client> | crawl delta, broken-link alerts, robots/sitemap drift | | /smartspec:weekly <client> | WoW trend analysis on tech metrics |

Per-module audits (use as a flag on the orchestrator):

/smartspec:audit acme --only schema
/smartspec:audit acme --only performance,images

Modules: a11y, analytics, content, hreflang, images, links, ai-readiness (alias llms), mobile, performance, redirects, robots, schema, security, sitemap, social, page.

Each module:

1. Calls smartspec audit <url> --only=<name> --format=json as the primary detection engine.
2. Enriches with a matching Python helper in .claude/skills/tech/_scripts/.
3. Writes findings/tech-<name>-YYYY-MM-DD.json + a Markdown report.

Finding aggregation: smartspec emits one finding per rule, not per page. A rule that fires on 36 pages produces a single finding listing all 36 URLs. The title is prefixed with "36 pages: …" and the evidence shows a sample. See .claude/skills/tech/_finding-schema/SKILL.md §Aggregation.

See AGENTS.md §Slash commands and .claude/skills/tech/_resources/references/skill-map.md for the full inventory. Run smartspec help for the CLI reference.

Dashboard

After running one or more audits, open the Kanban view:

smartspec dashboard
# Dashboard ready: http://localhost:4321

Findings are grouped per hostname under ~/.smartspec/findings/. Each finding moves through backlog → todo → doing → done columns; the JSON file mutates in place when you drag a card. Run a new audit on the same host and the dashboard offers a reload badge within 5 seconds.

Flags:

• --port <n> — pick a specific port (default: first free in 4321–4330)
• --open — open the browser automatically
• --prune <N>d — delete audits older than N days

Quick start

cd /Users/antonio/Desktop/smartweb_media/technical-seo
cp .env.example .env             # then fill in real vault refs
npm install                      # nothing to install — present for cross-tool parity
npm run doctor                   # verify wiring
npm run seo -- status            # compact tool status
npm run web                      # open the frontend app

Frontend app:

http://localhost:3000

Create a client and run checks:

npm run seo -- init acme --name "Acme" --domain acme.example --language it --country IT
npm run seo -- crawl acme --max-pages 25
npm run seo -- health acme

Available CLI commands:

npm run seo -- doctor
npm run seo -- status
npm run seo -- init <slug> --name <name> --domain <domain>
npm run seo -- crawl <client>
npm run seo -- health <client>
npm run seo -- audit <client>
npm run seo -- page <client> --url https://example.com/page
npm run seo -- schema <client>
npm run seo -- links <client>
npm run seo -- images <client>
npm run seo -- security <client>
npm run seo -- performance <client>
npm run seo -- llms <client>

The frontend exposes the same audit modules and writes machine-readable findings to findings/, Markdown reports to reports/, and snapshots to history/.

To use the Claude workspace directly:

./.claude/bin/claude-wrap
/smartspec:status                            # overview
/smartspec:audit <client>                    # full-site audit (all modules)
/smartspec:audit <client> --only schema      # single-module slice
/smartspec:page <client> <url>               # single-page deep audit
/smartspec:daily <client>                    # daily delta + alerts
/smartspec:weekly <client>                   # WoW trends

Layout

See CLAUDE.md §Project structure.

Boundaries

This workspace performs only the technical-SEO checks listed above. Anything outside that list belongs in a different workspace (e.g. studio/).

Tests

npm test                   # leakage gate + pytest
npm run test:leakage       # only the grep gate
npm run test:scaffold      # only the structure tests
npm run test:scripts       # only the script-import smoke tests

CLI (in development, Phase 1)

A standalone single-binary CLI is being built under src/ as a pivot toward a public product. See [[2026-05-23-squirrelscan-style-cli-pivot-design]] for the design and [[2026-05-23-cli-pivot-phase1-foundation]] for the Phase 1 implementation plan.

Binary name: smartspec.

Build locally:

bash scripts/build.sh         # host target → dist/smartspec
bash scripts/build-all.sh     # all 6 supported OS targets
bash tests/smoke.sh           # exercise all commands

Try it (after build.sh):

./dist/smartspec audit https://example.com -f json -m 1 -q
./dist/smartspec doctor
./dist/smartspec version

The CLI currently reuses the existing audit engine in src/audit/ (copied from web/lib/audit/ in Phase 1; will be refactored to the new AuditModule interface in Phase 3). The web app under web/ remains independently functional.

Use with AI agents

smartspec ships an audit-website skill for AI coding assistants. They invoke smartspec audit <url> and walk users through fixes for them.

Claude Code: the skill is auto-discovered from .claude/skills/audit-website/SKILL.md. No setup needed.

Cursor: copy .cursor/rules/audit-website.md from this repo into your project's .cursor/rules/ directory.

Other agents: point the agent at smartspec audit <url> -f llm and it will parse the LLM-optimized output natively.

Designed for vibecoders — users of Lovable, Bolt, v0, Replit, Cursor — whose sites typically fail Google indexing for predictable reasons (noindex residuals from preview envs, missing viewport tags, placeholder analytics IDs, default titles like "v0 by Vercel"). smartspec recognizes those patterns and names the tool in the fix message.