aisurface 1.0.1__tar.gz

aisurface-1.0.1/.gitattributes

@@ -0,0 +1,22 @@
+# Normalize line endings to LF (cross-platform consistency)
+* text=auto eol=lf
+
+# Python source must use LF
+*.py text eol=lf
+*.pyi text eol=lf
+
+# YAML, TOML, Markdown
+*.yml text eol=lf
+*.yaml text eol=lf
+*.toml text eol=lf
+*.md text eol=lf
+
+# Shell scripts need LF (not CRLF on Windows)
+*.sh text eol=lf
+
+# Binary by default
+*.png binary
+*.jpg binary
+*.gif binary
+*.ico binary
+*.pdf binary

aisurface-1.0.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: Something is broken
+---
+
+**Describe the bug**
+<description>
+
+**To reproduce**
+```bash
+<command>
+```
+
+**Expected behavior**
+<expected>
+
+**Environment**
+- OS:
+- Python version:
+- aisurface version:

aisurface-1.0.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,13 @@
+---
+name: Feature request
+about: Suggest a new feature
+---
+
+**Problem**
+<what problem does this solve>
+
+**Proposed solution**
+<how would it work>
+
+**Alternatives considered**
+<other approaches>

aisurface-1.0.1/.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,10 @@
+---
+name: Question
+about: Ask the maintainers
+---
+
+**Question**
+<your question>
+
+**Context**
+<what you've tried>

aisurface-1.0.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## What
+<what this PR does>
+
+## Why
+<why this change is needed>
+
+## Testing
+- [ ] All pytest tests pass
+- [ ] Ruff passes
+- [ ] Added/updated tests for the change
+- [ ] If adding a new GEO check, added eval fixture

aisurface-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install uv
+        run: pip install uv
+      - name: Install dependencies
+        run: uv pip install --system -e ".[dev]"
+      - name: Ruff
+        run: ruff check .
+      - name: Pytest (unit + integration, not eval)
+        run: pytest -m "not eval"
+      - name: Pytest (eval)
+        run: pytest -m eval

aisurface-1.0.1/.gitignore

@@ -0,0 +1,226 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Internal release handoff (kept local, not committed)
+RELEASE_HANDOFF.md
+
+# Git worktrees (per superpowers:using-git-worktrees)
+.worktrees/

aisurface-1.0.1/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+## [1.0.1] - 2026-06-03
+
+### Added
+- **User-facing abstraction principle** (spec §11b): unified `SKILL.md` exposes capabilities in plain language; hides CLI flags, subcommand names, and storage paths from skill consumers
+- 18 trigger-eval queries (`evals/trigger_evals.json`: 10 should-trigger, 8 should-not) for SKILL.md description optimization
+- **GEB fractal documentation system**: L1 in `CLAUDE.md`, L2 in each module's `CLAUDE.md` (scripts/, skills/, references/, tests/, evals/), L3 `INPUT/OUTPUT/POS/PROTOCOL` file headers in all 23 `scripts/*.py`
+
+### Changed
+- `README.md` and `README.en.md` now lead with `npx skills add ruijayfeng/aisurface`; `pip install` reframed as an implementation detail invoked by the skill on first run
+- `ROADMAP.md` aligned with the skill-first install story
+
+### Fixed
+- L3 file headers: `from __future__ import annotations` is now the first statement in all 23 `scripts/*.py` (was broken when L3 was a separate string preceding the original docstring, which Python rejected as a non-future import)
+
+## [1.0.0] - 2026-06-02
+
+### Added
+- PyPI publish-ready: classifiers + project URLs (hatchling-built wheel, `packages = ["scripts"]`)
+- 3-verb CLI documented in single root SKILL.md
+- `case-studies/ziwei-v100.md`: real-world before/after using the full v1.0 loop
+
+### Changed
+- Consolidated 3 SKILL.md files into 1 (`@readme` and `@llms-txt` moved to `skills/_deprecated/`)
+- README rewritten with 3-verb opening + screenshots
+
+### Removed
+- `scripts/probe.py` stub (already gone in v0.1.3)
+- The original "skill collection" decomposition: now 1 unified CLI + skill
+
+### Deprecated
+- `skills/_deprecated/aisurface-readme/SKILL.md` — use `aisurface fix .`
+- `skills/_deprecated/aisurface-llms-txt/SKILL.md` — use `aisurface fix . --only=llms_txt`
+- Both deprecated SKILL.md files will be removed in v1.1.
+
+## [0.1.3] - 2026-06-02
+
+### Added
+- `aisurface verify` subcommand: probes AI platforms for citation rate
+  - PerplexityAdapter (real API client, mocked in tests)
+  - Query generator with per-project-type templates (10 queries default)
+  - Baseline store at `~/.aisurface/baselines/<hash>/<platform>.json`
+  - `--platforms`, `--baseline`, `--queries-file` flags
+- Custom cache dir via `AISURFACE_CACHE_DIR` env var (mainly for testing)
+- Actionable error when `PERPLEXITY_API_KEY` is missing
+
+### Changed
+- Removed legacy `scripts/probe.py` stub (replaced by `scripts/verify/` module)
+
+### Tests
+- 105 tests passing (up from 89 in v0.1.2)
+
+## [0.1.2] - 2026-06-02
+
+### Added
+- `aisurface fix` subcommand: generates and applies patches for the 4 highest-impact must-fix items
+  - FAQ injection (templated 8 Q&A per project type, defaults to "generic")
+  - When-to-use stubs (both halves or just the missing one)
+  - `.well-known/llms.txt` (new file, per llmstxt.org spec)
+  - `index.schema.json` (SoftwareApplication + FAQPage)
+- `fix` flags: `--dry-run`, `--yes`, `--only=faq,when_to_use,llms_txt,schema_org`
+- Snapshot tests for patch output (`evals/expected_patches/`)
+
+### Changed
+- CLI now uses subparsers: `aisurface audit ./` (was `python -m scripts.cli ./`)
+- Old direct invocation `python -m scripts.cli ./` requires `audit` subcommand
+- `scripts/audit.py` split out from `scripts/cli.py` for separation of concerns
+
+### Tests
+- 89 tests passing (up from 67 in v0.1.1)
+
+## [0.1.1] - 2026-06-02
+
+### Added
+- 4th eval fixture: `perfect-readme-and-docs` (sanity-check audit upper bound; hits 96/100 weighted, all 12 checks pass)
+- `StructuralFinding(CheckResult)` typed subclass with `file_path` field for file-based structural checks (#5 schema.org, #6 llms.txt)
+- `@safe_check` decorator skeleton (v0.3 interface; v0.1.1 staging — catch path exercised only in tests)
+- Weighted health score (Citation-Friendliness 40 / Structure 30 / Readability 20 / Distribution 10) replacing the v0.1.0 equal-weight formula
+- ANSI color output for the CLI (auto-detected, `--no-color` opt-out, `NO_COLOR` env var support)
+- `--no-color` CLI flag (documented in SKILL.md)
+
+### Changed
+- `_compute_health_score` now takes a `categories: dict[str, list[CheckResult]]` and returns `(score, max_score=100)` instead of a flat sum/max ratio
+- `AuditReport` gains `health_score: int` and `max_score: int` fields (defaults `0` and `100`)
+- `render_report` now shows 4 sub-scores (one per category) instead of 2
+- `CheckResult` gains `skipped: bool` and `error: str | None` fields (defaults `False` and `None`)
+- `AuditReport` gains `skipped: list[CheckResult]` and `errors: list[str]` fields (v0.3 staging; empty in v0.1.1)
+- `--json` output now includes `skipped` and `error` keys per result row
+- Distribution check #11 threshold lowered from 6 to 5 (v0.1's `github_stars=0` stub made 6 unreachable; threshold matches the locally-observable max from registries + description)
+- Distribution check #11 now reads real `has_npm`/`has_pypi` from the scanner (was hardcoded `False`); `RepoAssets` gains those two fields
+- `offline_critique` removed arbitrary 9→10 sub-ceilings on `has_faq` and `has_code_examples` (unambiguous max signals)
+- 4 eval fixtures' expected JSONs re-recorded (the 3 v0.1.0 fixtures plus the new 4th)
+- CHANGELOG "Known gaps for v0.1.1" subsection under `[0.1.0]` removed (4 of 5 items delivered, remaining deferred to v0.1.2+)
+
+### Tests
+- 67 tests passing (up from 54 in v0.1.0)
+
+## [0.1.0] - 2026-07-15
+
+### Added
+- `aisurface@audit` skill: 12-check GEO audit
+- `aisurface@readme` skill: README optimization
+- `aisurface@llms-txt` skill: generate `.well-known/llms.txt`
+- Python scripts: scanner, schema_gen, llms_txt, github_meta, distribution, critic, report, cli
+- 3 eval fixtures: bad-readme-python-lib, good-schema-nextjs-docs, minimal-cli-tool
+- Bilingual README (zh + en)
+- Case study: ruijayfeng/ziwei before/after

aisurface-1.0.1/CLAUDE.md

@@ -0,0 +1,49 @@
+# aisurface — Make your open-source project surface in AI search results
+
+> L1 | Python 3.10+ + httpx + jsonschema + selectolax + pytest + ruff
+
+## Current State
+**Shipped**: v0.1.1 (tag pushed 2026-06-02). `audit` command works end-to-end (67 tests, 4 eval fixtures).
+**In progress**: v1.0 — unify 3 skills into 1, add `fix` + `verify` verbs, publish to PyPI. See `ROADMAP.md` and `docs/superpowers/plans/2026-06-02-aisurface-v100.md`.
+
+## Architecture Principles
+- **Skill-first install.** The primary user entry point is `npx skills add ruijayfeng/aisurface`. `pip install aisurface` is an implementation detail handled by the skill at first invocation. See `docs/superpowers/specs/2026-06-02-aisurface-v100-design.md` §11b.
+- **User-facing abstraction.** The `SKILL.md` exposes capabilities in plain language and hides CLI flags, subcommand names, and storage paths. See same spec §3 + §11b.
+- **GEB fractal docs.** L1 here, L2 in each module's `CLAUDE.md`, L3 as file-header contracts in `scripts/*.py`. Every change touches its layer.
+
+## Directory
+```
+aisurface/
+├── SKILL.md              - Unified skill definition (name: aisurface), single user-facing surface
+├── scripts/              - Python implementation (cli, audit, report, fix/, verify/, scanner, ...)
+├── skills/
+│   └── _deprecated/      - v0.1.x sub-skills (aisurface-readme, aisurface-llms-txt) — will be removed in v1.1
+├── tests/                - pytest suite (unit/ + integration/)
+├── evals/                - Fixture-based eval suite + trigger_evals.json (for skill description optimization)
+├── references/           - Knowledge base (AI platforms, schema templates, GEO checklist, llms.txt spec)
+├── case-studies/         - Real-world before/after (ziwei is the canonical case)
+├── docs/
+│   ├── superpowers/
+│   │   ├── plans/        - Implementation plans (this plan + the v1.0 plan)
+│   │   └── specs/        - Specs (v1.0 design, etc.)
+│   └── (user-facing docs land here)
+├── .github/              - CI workflow + issue/PR templates
+└── CLAUDE.md             - This file (L1)
+```
+
+## Config Files
+- `pyproject.toml` — package metadata, deps, console script `aisurface = scripts.cli:main`, pytest/ruff config
+- `ROADMAP.md` — release sequence (v0.1.0 → v1.0)
+- `CHANGELOG.md` — release notes
+- `README.md` / `README.en.md` — bilingual project README (lead with `npx skills add` + natural-language demo)
+- `SKILL.md` — root skill descriptor (unified `aisurface`)
+
+## Active Specs & Plans
+- **v1.0 design**: `docs/superpowers/specs/2026-06-02-aisurface-v100-design.md` (or sibling-repo mirror)
+- **v1.0 plan**: `docs/superpowers/plans/2026-06-02-aisurface-v100.md` (or sibling-repo mirror)
+- **Skill optimization plan** (this one): `docs/superpowers/plans/2026-06-03-aisurface-skill-optimization-and-v1-bridge.md`
+
+## Rule
+Minimal · stable · navigation. Update on any architecture-level change (new module, file move, responsibility shift, skill structure change, install story change).
+
+[PROTOCOL]: Update this header when changed, then check all L2 CLAUDE.md files and the L3 file headers in scripts/.

aisurface-1.0.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,29 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We pledge to make participation in our project a welcoming and inclusive experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+- The use of sexualized language or imagery
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct that could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at `conduct@ruijayfeng.com` or via [GitHub Issues](https://github.com/ruijayfeng/aisurface/issues). All complaints will be reviewed and investigated.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0.

aisurface-1.0.1/CONTRIBUTING.en.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Welcome to contribute to aisurface!
+
+## Issues
+
+- **Bug**: use the `Bug report` template
+- **Feature request**: use the `Feature request` template
+- **Question**: use the `Question` template
+
+## Pull Requests
+
+1. Fork → change → PR
+2. One PR per change
+3. All PRs must pass CI (ruff + pytest)
+4. Add tests covering your change
+
+## Dev environment
+
+```bash
+git clone https://github.com/ruijayfeng/aisurface.git
+cd aisurface
+pip install -e ".[dev]"
+pytest
+```
+
+## Adding a new GEO check
+
+`scripts/scanner.py` + `scripts/cli.py` are the main extension points.
+
+Each check must:
+- Run without crashing on 2 eval fixtures
+- Add a fixture in `tests/integration/test_full_audit.py`
+- Update `references/readme-checklist.md`

aisurface-1.0.1/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# 贡献指南
+
+欢迎为 aisurface 贡献！
+
+## 提 issue
+
+- **Bug**: 用 `Bug report` 模板
+- **功能建议**: 用 `Feature request` 模板
+- **问题咨询**: 用 `Question` 模板
+
+## 提 PR
+
+1. Fork → 改 → PR
+2. 一个 PR 一个改动
+3. 所有 PR 必须过 CI（ruff + pytest）
+4. 添加测试覆盖你的改动
+
+## 开发环境
+
+```bash
+git clone https://github.com/ruijayfeng/aisurface.git
+cd aisurface
+pip install -e ".[dev]"
+pytest
+```
+
+## 添加新的 GEO 检查
+
+`scripts/scanner.py` + `scripts/cli.py` 是主要扩展点。
+
+每个检查必须：
+- 跑在 2 个 eval fixture 上不 crash
+- 在 `tests/integration/test_full_audit.py` 添加 fixture
+- 更新 `references/readme-checklist.md`

aisurface-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jay Feng
+
+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.