Skip to content

ziwei-v100.md

Latest commit

 

History

History
79 lines (56 loc) · 3.92 KB

ziwei-v100.md

File metadata and controls

79 lines (56 loc) · 3.92 KB

Dogfooding v1.0 on ruijayfeng/ziwei

Date: 2026-06-02 Project: ruijayfeng/ziwei (343-star 紫微斗数 web app) Stack: React 19 + TypeScript + Vite aisurface version: v0.1.3 (worktree pointing to v1.0 plan)

Baseline

  • aisurface audit . score: 35 / 100
  • Sub-scores: Citation-Friendliness 50 / Distribution 55 / Readability 23 / Structure 17
  • 5 🔴 Must-fix items:
    1. Schema.org markup on website (impact +20%)
    2. .well-known/llms.txt present (impact +15%)
    3. README has FAQ section (impact +15%)
    4. README when to use / not to use (impact +10%)
    5. When to use / not to use in README (impact +8%)

Applied patches

4 patches from aisurface fix . --yes (took ~3 seconds wall-clock):

  1. FAQ section (8 Q&A template stubs appended to README)
  2. When-to-use / When-NOT-to-use sections (2 stub sections appended to README)
  3. .well-known/llms.txt (12-line file per llmstxt.org spec, new file)
  4. index.schema.json (SoftwareApplication + FAQPage JSON-LD, new file)
Generated 4 patch(es):
  [faq] EDIT README.md — FAQ section (8 Q&A, template: generic)
  [when_to_use] EDIT README.md — When-to-use sections (both)
  [llms_txt] NEW  .well-known\llms.txt — .well-known/llms.txt (per llmstxt.org spec, 12 lines)
  [schema_org] NEW  index.schema.json — index.schema.json (SoftwareApplication + FAQPage)

✓ Applied [faq] to D:\Code\MyProject\ziwei\README.md
✓ Applied [when_to_use] to D:\Code\MyProject\ziwei\README.md
✓ Applied [llms_txt] to D:\Code\MyProject\ziwei\.well-known\llms.txt
✓ Applied [schema_org] to D:\Code\MyProject\ziwei\index.schema.json

All 4 patches are visible in the ziwei working tree (untracked, not yet committed — that's intentional; the case study captures the loop, not a release PR).

After

  • aisurface audit . score: 87 / 100
  • Sub-scores: Citation-Friendliness 100 / Distribution 55 / Readability 83 / Structure 83
  • 0 🔴 Must-fix (5 → 0)
  • Lift: +52 points (35 → 87, a 149% relative improvement)

The only remaining items the audit flagged were:

  • GitHub topics complete (8-12) — impact +5%, not auto-fixable
  • Distribution signals (awesome / npm / PyPI) — impact +5%, not auto-fixable
  • README problem statement (Nice-to-have, +20%)

Verify (skipped)

aisurface verify . requires a PERPLEXITY_API_KEY. None was configured in this dev environment, so the verify step was skipped. The verify command prints a clear actionable error and exits non-zero:

Error: PERPLEXITY_API_KEY not set. Get a key at https://perplexity.ai/account/api

Honest gaps

The auto-generated stubs contain <TODO: ...> placeholders. For example:

  • .well-known/llms.txt has <TODO: e.g. MIT> and <TODO: e.g. Python> for license / language
  • index.schema.json has <TODO: 1-sentence description of ziwei> and <TODO: project URL, ...> for description / URL
  • README FAQ section has 8 empty <TODO: question?> / <TODO: answer> pairs

The audit treats these placeholders as passing because the structural signal (FAQ section exists, schema file exists, llms.txt exists) is what AI search crawlers need to index. The semantic content needs a human pass to replace TODOs with real text. This is a known v0.1 design choice — the loops prioritizes "get the file in place" over "write the perfect content."

For a real production push, plan ~20 minutes of human edit after fix to fill in TODOs from your project's actual context.

Takeaway

audit → fix → re-audit works end-to-end in v1.0: a 35 → 87 lift on a real 343-star repo, in under 30 seconds of wall-clock time, with zero human writing. The remaining gaps (TODO placeholders, GitHub topics, distribution signals) are all clearly identified and bounded — easy to fix manually, not a blocker for the v1.0 release.

The verify step is the only path that needs a real Perplexity key to be meaningful; documenting that as a pre-release setup step is part of Task 18.