chore: clarify landing copy + extract design system#48
Merged
johnnichev merged 2 commits intomainfrom Apr 7, 2026
Merged
Conversation
Em-dashes are a known AI-tell when used as the load-bearing punctuation of every section. This pass removes them from all user-visible copy on the landing page. Source-code comments (CSS/HTML/JS) keep their em-dashes because that's legitimate developer prose, not marketing copy. User-facing changes: - <title>: "Selectools — Production-Ready..." → "Selectools: Production-Ready..." - og:title, twitter:title: same separator swap - twitter:description: drop em-dash, use period - JSON-LD FAQ answer: "...native tool calling — no chains..." → "...native tool calling. No chains..." - #what description: "...no paid SaaS — your code stays plain Python." → "...no paid SaaS. Your code stays plain Python." - Why vignette pain text: "Your agent did something — you have no idea what." → "Your agent did something. You have no idea what." - #see-difference description: "Same outcome — 25 lines of ceremony, or one." → "Same outcome. 25 lines of ceremony, or one." - Code-comment in #see-difference example: same period swap - #enterprise test counter caption: "...e2e — green on every commit." → "...e2e. Green on every commit." - ML/AI persona answer: "Not just while you're debugging — always on..." → "Not just while you're debugging. Always on..." Also caught three other AI tells in the simulation panel strings: - "leverages quantum mechanics principles" → "uses quantum mechanics principles" - "delivers tokens in real time while seamlessly handling tool calls" → "yields tokens in real time and handles tool calls" - "Write a comprehensive guide to machine learning" → "Write a complete guide to machine learning" 12 user-visible strings touched. Zero markup or layout changes.
Distills the implicit visual language from landing/index.html into docs/design-system.md, a 401-line reference that future design AI work can read to stay coherent with what's already shipped. Sections: 1. Design tokens — colors, type scale, spacing, radii, easing, breakpoints, touch targets, glow tokens for the execution-pointer system. All cross-referenced to the :root CSS vars in landing/index.html. 2. Component inventory — every reusable class with its purpose, layout role, and which section uses it. Includes the layout shells, code frames, buttons, cards, bento, the execution-pointer atoms (.exec-dot / .exec-caret / .exec-scan / @Keyframes exec-stamp), and the section-specific components (.what-stage, .diff-pane, .prod-trace, .ent-shelf, .eval-report, .repl, .footer-term, .wm--N). 3. Animation language — the IntersectionObserver reveal pattern, stagger recipes via inline --delay vars, the rule that every animated component must have a prefers-reduced-motion fallback. 4. Voice & tone rules — banned punctuation (em-dashes), banned words (leverage, seamless, robust, comprehensive, navigate-figurative, delve, elevate, unlock-figurative, etc.), sentence structure rules, and the "earned confidence not arrogance" tone target. 5. Anti-patterns — 10 specific don'ts captured from real bugs we hit and corrected (inline grid placements without mobile reset, clip-path var() recompute trap, <nav> selector hoisting, hide-mobile specificity, etc.). 6. File structure — where each piece of design context lives. 7. When to update — explicit triggers for keeping the doc in sync. Also updates .impeccable.md with a companion-document link so future agents discover both files. .impeccable.md is the *why* (brand, voice, principles); design-system.md is the *what* (the actual tokens and component classes).
johnnichev
added a commit
that referenced
this pull request
Apr 7, 2026
… + AI Overview triggers Comprehensive SEO and AI-SEO pass against the landing page and docs. Verified with Playwright: 4 valid JSON-LD schemas (SoftwareApplication with 28 props, Organization, HowTo, FAQPage with 13 questions), 1 H1, 13 H2s, canonical correct, OG image PNG referenced. ## Stale data fixes (high impact for AI search citations) - llms.txt: "3344 tests" → "4612 tests at 95% coverage" - llms.txt: "76 examples" → "88 examples" - llms.txt: dropped em-dash on line 5 (consistent with the clarify rule from PR #48) - llms.txt: replaced em-dashes inside the code-comment block with -> arrows (still legible, no AI-tell) - SoftwareApplication.featureList: "24 pre-built tools" → "33 across 9 categories" - SoftwareApplication.featureList: every entry expanded with specific numbers (15 guardrails, 8 builder nodes, 7 templates, 4612 tests, 95% coverage) ## SoftwareApplication schema enrichment Added properties that AI crawlers and Google rich results reward: - applicationSubCategory: "AI Agent Framework" - softwareRequirements: explicit Python version list - installUrl - datePublished + dateModified (freshness signal) - inLanguage - isAccessibleForFree: true - publisher (NichevLabs) - maintainer (Person with email + GitHub URL) - image + screenshot (both point to og-image.png) - offers.availability + offers.url - keywords (broader than the meta keywords) ## New: Organization schema NichevLabs Organization JSON-LD with logo, founder, sameAs links to GitHub and PyPI. Helps establish entity identity in Google's knowledge graph and gives AI crawlers a clean entity to cite. ## New: HowTo schema (AI Overview trigger) How-to JSON-LD for "install Selectools and run your first AI agent in Python" with 3 explicit steps (install, create file, run). Each step has position, name, text, and url linking to the Quickstart section. AI Overviews and Google rich results frequently elevate HowTo schemas for "how to..." queries. ## FAQPage schema additions (5 → 13 questions) Added 4 new questions targeting common AI Overview triggers that the existing 9 didn't cover: - "Is Selectools free?" — direct yes/no AI Overview hit - "How does Selectools compare to CrewAI?" - "How does Selectools compare to AutoGen?" - "What is the difference between Selectools and LangGraph?" These match the literal phrasings users type into ChatGPT, Perplexity, and Google AI Overview when researching agent frameworks. ## docs/index.md: meta description Added a frontmatter `description:` field so MkDocs Material renders a per-page meta description tag on the docs landing page (was missing). ## docs/CLAUDE.md: search exclusion (partial) Added MkDocs frontmatter `search.exclude: true` to keep the internal agent-instruction file out of the docs search index. NOTE: this does NOT remove it from the sitemap.xml — full sitemap exclusion requires either the `mkdocs-exclude` plugin (out of scope for this PR) or moving docs/CLAUDE.md outside the docs/ directory entirely. The search exclusion is the 80% fix. ## mkdocs.yml: not_in_nav Added CLAUDE.md and RELEASE_GUIDE.md to the not_in_nav list so the build no longer warns about them being in docs/ but not in the nav.
6 tasks
johnnichev
added a commit
that referenced
this pull request
Apr 7, 2026
… + AI Overview triggers (#50) Comprehensive SEO and AI-SEO pass against the landing page and docs. Verified with Playwright: 4 valid JSON-LD schemas (SoftwareApplication with 28 props, Organization, HowTo, FAQPage with 13 questions), 1 H1, 13 H2s, canonical correct, OG image PNG referenced. ## Stale data fixes (high impact for AI search citations) - llms.txt: "3344 tests" → "4612 tests at 95% coverage" - llms.txt: "76 examples" → "88 examples" - llms.txt: dropped em-dash on line 5 (consistent with the clarify rule from PR #48) - llms.txt: replaced em-dashes inside the code-comment block with -> arrows (still legible, no AI-tell) - SoftwareApplication.featureList: "24 pre-built tools" → "33 across 9 categories" - SoftwareApplication.featureList: every entry expanded with specific numbers (15 guardrails, 8 builder nodes, 7 templates, 4612 tests, 95% coverage) ## SoftwareApplication schema enrichment Added properties that AI crawlers and Google rich results reward: - applicationSubCategory: "AI Agent Framework" - softwareRequirements: explicit Python version list - installUrl - datePublished + dateModified (freshness signal) - inLanguage - isAccessibleForFree: true - publisher (NichevLabs) - maintainer (Person with email + GitHub URL) - image + screenshot (both point to og-image.png) - offers.availability + offers.url - keywords (broader than the meta keywords) ## New: Organization schema NichevLabs Organization JSON-LD with logo, founder, sameAs links to GitHub and PyPI. Helps establish entity identity in Google's knowledge graph and gives AI crawlers a clean entity to cite. ## New: HowTo schema (AI Overview trigger) How-to JSON-LD for "install Selectools and run your first AI agent in Python" with 3 explicit steps (install, create file, run). Each step has position, name, text, and url linking to the Quickstart section. AI Overviews and Google rich results frequently elevate HowTo schemas for "how to..." queries. ## FAQPage schema additions (5 → 13 questions) Added 4 new questions targeting common AI Overview triggers that the existing 9 didn't cover: - "Is Selectools free?" — direct yes/no AI Overview hit - "How does Selectools compare to CrewAI?" - "How does Selectools compare to AutoGen?" - "What is the difference between Selectools and LangGraph?" These match the literal phrasings users type into ChatGPT, Perplexity, and Google AI Overview when researching agent frameworks. ## docs/index.md: meta description Added a frontmatter `description:` field so MkDocs Material renders a per-page meta description tag on the docs landing page (was missing). ## docs/CLAUDE.md: search exclusion (partial) Added MkDocs frontmatter `search.exclude: true` to keep the internal agent-instruction file out of the docs search index. NOTE: this does NOT remove it from the sitemap.xml — full sitemap exclusion requires either the `mkdocs-exclude` plugin (out of scope for this PR) or moving docs/CLAUDE.md outside the docs/ directory entirely. The search exclusion is the 80% fix. ## mkdocs.yml: not_in_nav Added CLAUDE.md and RELEASE_GUIDE.md to the not_in_nav list so the build no longer warns about them being in docs/ but not in the nav.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Two passes against the landing page and project design context:
Pass 1: clarify
Em-dashes in body copy read as AI-generated when every section uses one as the load-bearing punctuation. This pass removes them from all user-visible strings. Replaced with periods, colons, or rewrites depending on what each one was doing.
Changes
Other AI tells caught in simulation strings
12 user-visible strings touched. Zero markup or layout changes. Verified visually with Playwright that nothing broke.
Pass 2: design system
Created `docs/design-system.md` (401 lines) covering:
Also updates `.impeccable.md` (the existing design context file) with a companion-document link so future agents discover both files. `.impeccable.md` is the why (brand, voice, principles); `design-system.md` is the what (tokens, classes, patterns).
Test plan