@cratis/pi 7.97.1 → 7.98.0

package/package/corpus/harnesses/copilot/instructions/discoverability.instructions.md

@@ -30,5 +30,12 @@ Readability comes first. If a change for search engines or AI assistants makes a
 
 - Public pages need a canonical link, one `<h1>`, Open Graph tags, valid JSON-LD that describes visible content, a sitemap entry and a `robots.txt` that allows crawling. Add no new `HowTo` or `FAQPage` markup; keep the visible Q&A.
 - `llms.txt` is an optional index. Never claim it improves ranking. See **cratis-llm-friendly-documentation**.
-- Package metadata (`Description`, `PackageProjectUrl`, `PackageTags`, npm `description`, `homepage`, `keywords`) and the README opener use the same definition sentence, and the project URL points at the docs page `https://www.cratis.io/<product>/`.
+- Package metadata uses `Cratis` for Authors and Company. Metadata (`Description`, `PackageProjectUrl`, `PackageTags`, npm `description`, `homepage`, `keywords`) and the README opener use the same definition sentence, and the project URL points at the docs page `https://www.cratis.io/<product>/`.
 - State only facts the repository supports: versions, licenses, limits. The claim gate in `BRAND.md`, `MESSAGING.md` and `SITE.md` still applies.
+
+## Facts and publication guardrails
+
+- Each entity page has one sourced "at a glance" block: verifiable facts only, dated counts; never invent customers, user counts, benchmarks, certifications, prices or competitor comparisons.
+- Adoption claims count downloads per product through entry packages only, including predecessor names for a continuation; no sub-package sums or shared-dependency double counting. Round down to a stated threshold, name the month and registries, never say "users" or "customers".
+- Keep description and duplicate-title lint baselines at 0; never raise a baseline to pass. Preserve product names in rendered titles and enforce the site's `llms.txt` / `llms-small.txt` byte budgets.
+- Structured data uses only public, owner-approved founder/company facts. Community member profiles are `noindex`, with no personal data or `Person` entities in markup; this overrides the public-page indexing default above. Keep shared guidance generic: no private/unannounced integration names, legal entity details or factual counts.

package/package/corpus/hooks/README.md

@@ -645,6 +645,14 @@ the intended action and the permitted alternative; it does not loosen its own co
 Supply credentials through the environment, never echo them or place them in committed files.
 A missing or disabled hook is not evidence that a protected action is safe.
 
+The shipped `permissions.ask` rules (`git push`, `gh pr`) are for a person at a terminal. In
+`claude -p` an `ask` rule wins over `--dangerously-skip-permissions`, and with nobody to answer,
+the call is denied. A runner whose work includes pushing or opening pull requests answers those
+prompts with `--permission-prompt-tool` (an MCP tool that returns an allow decision); `deny` rules
+and denying hooks are settled first and still refuse. Do not drop the project settings with
+`--setting-sources user` instead: on Claude Code 2.1.280 that also stops the repository's
+`CLAUDE.md`, skills and hooks from loading.
+
 ## Method lineage
 
 | Idea | Used in | Credit |

package/package/corpus/rules/discoverability.md

@@ -29,5 +29,12 @@ Readability comes first. If a change for search engines or AI assistants makes a
 
 - Public pages need a canonical link, one `<h1>`, Open Graph tags, valid JSON-LD that describes visible content, a sitemap entry and a `robots.txt` that allows crawling. Add no new `HowTo` or `FAQPage` markup; keep the visible Q&A.
 - `llms.txt` is an optional index. Never claim it improves ranking. See **cratis-llm-friendly-documentation**.
-- Package metadata (`Description`, `PackageProjectUrl`, `PackageTags`, npm `description`, `homepage`, `keywords`) and the README opener use the same definition sentence, and the project URL points at the docs page `https://www.cratis.io/<product>/`.
+- Package metadata uses `Cratis` for Authors and Company. Metadata (`Description`, `PackageProjectUrl`, `PackageTags`, npm `description`, `homepage`, `keywords`) and the README opener use the same definition sentence, and the project URL points at the docs page `https://www.cratis.io/<product>/`.
 - State only facts the repository supports: versions, licenses, limits. The claim gate in `BRAND.md`, `MESSAGING.md` and `SITE.md` still applies.
+
+## Facts and publication guardrails
+
+- Each entity page has one sourced "at a glance" block: verifiable facts only, dated counts; never invent customers, user counts, benchmarks, certifications, prices or competitor comparisons.
+- Adoption claims count downloads per product through entry packages only, including predecessor names for a continuation; no sub-package sums or shared-dependency double counting. Round down to a stated threshold, name the month and registries, never say "users" or "customers".
+- Keep description and duplicate-title lint baselines at 0; never raise a baseline to pass. Preserve product names in rendered titles and enforce the site's `llms.txt` / `llms-small.txt` byte budgets.
+- Structured data uses only public, owner-approved founder/company facts. Community member profiles are `noindex`, with no personal data or `Person` entities in markup; this overrides the public-page indexing default above. Keep shared guidance generic: no private/unannounced integration names, legal entity details or factual counts.

package/package/corpus/skills/cratis-discoverability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cratis-discoverability
-description: Run the pre-publish check that makes Cratis content easy to find in search and AI answers without making it harder to read - a docs page, blog post, landing page, README or package metadata (title, description, opening definition, canonical links, entity names, alt text, structured data). Use when about to publish or review content for discoverability, SEO, AEO or GEO, or when writing package descriptions and README openers. Not for page voice and structure (cratis-documentation-writing), llms.txt design (cratis-llm-friendly-documentation), distribution plans (cratis-developer-marketing) or length decisions (cratis-content-length).
+description: Check Cratis content before publishing for search and AI answers without sacrificing readability. Use when reviewing discoverability, SEO, AEO or GEO; writing fact blocks or download claims; editing package/repo metadata; checking docs titles, descriptions or LLM export budgets; or reviewing founder/company JSON-LD and member profile indexing. Not for page voice and structure (cratis-documentation-writing), llms.txt design (cratis-llm-friendly-documentation), distribution plans (cratis-developer-marketing) or length decisions (cratis-content-length).
 license: MIT
 ---
 
@@ -13,13 +13,13 @@ drop the fix and say so.
 
 ## Procedure
 
-1. Name the content type: docs page, blog post, landing page, README or package metadata.
+1. Name the content type: docs page, blog post, landing page, README, package/repo metadata or member profile.
 2. Name the reader's one job and, for docs, the page type (tutorial, how-to, reference, explanation).
-3. Apply the checks for that type below. Fix the draft; do not annotate it.
+3. Apply the checks for that type below, including facts, adoption claims and privacy without waiting for a separate request. Fix the draft; do not annotate it.
 4. For a built site, run the checker and fix errors; warnings are judgment calls to report.
 5. Report what was changed, what was left alone and why.
 
-Read `references/page-checklist.md` for the full per-type checklist and the field lengths.
+Read `references/page-checklist.md` when checking a page, including docs lint baselines and LLM export budgets.
 
 ## Checks by content type
 
@@ -29,7 +29,9 @@ Read `references/page-checklist.md` for the full per-type checklist and the fiel
   definition sentence may follow the opening scenario where it reads naturally. `writing-cratis-docs`
   wins on voice and structure. Product index pages open with the definition sentence.
   Reference pages stay terse: title is the exact name plus its product, no question headings, no
-  intro. Titles are unique across the site and name the product ("Chronicle projections").
+  intro. Titles are unique across the site and name the product ("Chronicle projections"). Keep
+  description and duplicate-title lint baselines at 0; never raise a baseline to pass. Check
+  rendered titles and measure `llms.txt` / `llms-small.txt` bytes against the site budgets.
 - **Blog post.** The title states the topic in the words a reader would search. The intro gives the
   conclusion in two sentences. Show the named author and date, add `lastUpdated` only for real
   changes, link the owning docs pages with `https://www.cratis.io/...`, keep `description` apart
@@ -41,7 +43,19 @@ Read `references/page-checklist.md` for the full per-type checklist and the fiel
   nouns, with no logo-only or metaphor opener. Links are absolute; link the docs page.
 - **Package metadata.** One sentence naming what the package is and which Cratis product it belongs
   to, identical to the README opener. `PackageProjectUrl` and `homepage` point at the docs page, not
-  only at GitHub. Read `references/package-metadata.md` for the field map.
+  only at GitHub. Read `references/package-metadata.md` when editing package fields, GitHub About,
+  Docker Hub descriptions, analyzer help links, template messages or README footers. Check these
+  surfaces together; Authors and Company are `Cratis`.
+
+## Fact blocks and adoption claims
+
+For each entity page, assemble one sourced "at a glance" block from verifiable facts, with dates
+for counts. Read `references/facts-and-adoption.md` when selecting facts or calculating downloads:
+identify entry packages and continuation predecessors, exclude sub-packages and overlapping
+shared dependencies, round down to a stated threshold, and publish the month and registries.
+Downloads are never users or customers. Omit unsupported claims instead of inventing customers,
+user counts, benchmarks, certifications, prices or competitor comparisons. Keep shared guidance
+generic; do not copy private integration names, legal entity details or factual counts into it.
 
 ## Names
 
@@ -53,7 +67,10 @@ Do not invent a name, URL, maturity word or claim that the references do not sta
 
 Describe only what is visible on the page, one `@graph` per page, stable `@id`s. Add no `HowTo` and
 no new `FAQPage`. Read `references/structured-data.md` for the patterns and what each page type
-gets. Do not name people in structured data.
+gets. Use only public, owner-approved founder/company facts. Do not name other people in
+structured data; never add personal data or `Person` entities for community members. Member
+profiles are `noindex`; check profile and CV routes, rendered robots directives and JSON-LD.
+Without approved public founder facts, reference the organization by `@id` instead.
 
 ## Checking a built site
 

package/package/corpus/skills/cratis-discoverability/references/facts-and-adoption.md

@@ -0,0 +1,49 @@
+# Fact blocks and adoption numbers
+
+## At a glance
+
+1. Identify the entity the page defines. Add one visible "at a glance" block per entity page,
+   near its definition, not repeated promotional blocks throughout the page.
+2. Select only verifiable facts: what it is, license, public status, supported capabilities and
+   approved public company/founder facts. Attach a source to every fact; counts need both a
+   source and an as-of month. A date alone is not evidence.
+3. Check the source supports the exact wording. Distinguish vendor claims from independent
+   measurements; repository creation is not a founding date, and contributors are not employees.
+4. Omit anything unsupported. Never invent customers, user counts, benchmarks, certifications,
+   prices or competitor comparisons. Do not turn an unpublished term into a public promise.
+
+A minimal block can say `License: MIT ([license](<public source URL>))` after checking that
+source. Add a download row only after the calculation below. Keep the dated calculation and
+source links in the owning project's evidence, with one maintained source of truth for reused
+claims. Shared corpus guidance must not copy factual counts, legal entity details or names of
+private/unannounced integrations from that evidence.
+
+## Counting downloads
+
+1. Work per product, registry and era. List the user-installed entry packages or server images,
+   their public registry sources, observation month and counter meaning. Count entry packages
+   only: exclude sub-packages, add-ons and starter/meta-packages that repeat those installs.
+2. For a product continuation, include predecessor package names and explain the lineage from
+   public evidence. Distinct historical entry distributions may count; do not include an
+   unrelated product simply because it shares an organization or dependency.
+3. Record registry measurements and gaps: NuGet displayed totals may be rounded, npm totals
+   need complete time ranges, Docker Hub reports pulls, and Hex reports downloads. Do not
+   silently replace missing or incomplete measurements with estimates or claim an unmeasured
+   registry. These are downloads/pulls, not unique adoption.
+4. Sum the included entry counters once per product. Do not add shared dependencies to a
+   company headline: their downloads overlap consuming products. Avoid a cross-product total
+   unless its exclusions and overlap are documented; per-product claims are the default.
+5. Choose a conservative threshold below the supported total and round down, never to nearest
+   or up. Publish "more than <rounded threshold> downloads as of <month year>, across <named
+   registries>, including <public predecessor names>". For Docker, explain that pulls are part
+   of the combined measure. Never relabel downloads as users, customers, teams or installations.
+6. Recheck the calculation and source completeness before publishing. Keep one maintained
+   calculation for reuse; never change its date without refreshing the measurements. If evidence is incomplete, omit the claim and report the gap.
+
+## Verification
+
+A pass has one visible block per entity page, a working source for every fact, a date on every
+count, and a reproducible download calculation listing included entries, excluded dependencies,
+predecessors, registry coverage and rounding threshold. Compare visible wording and JSON-LD
+with those sources. No unsupported claim or private detail should remain; report missing
+sources rather than filling gaps.

package/package/corpus/skills/cratis-discoverability/references/package-metadata.md

@@ -4,6 +4,8 @@
 
 - Field map
 - Writing the description
+- Repository and distribution surfaces
+- Verification
 - Pitfalls
 
 ## Field map
@@ -14,7 +16,8 @@
 | Tags | `<PackageTags>`, 5-10, `cratis` plus category terms | `keywords`, the same list |
 | Project URL | `<PackageProjectUrl>` = `https://www.cratis.io/<product>/` | `homepage`, the same |
 | Repository | `RepositoryUrl` | `repository` |
-| Authors | `Cratis` | `author` `Cratis` |
+| Authors | `<Authors>Cratis</Authors>` (plural) | `author` `Cratis` |
+| Company | `<Company>Cratis</Company>` | No standard field; do not invent one |
 | License | `PackageLicenseExpression` `MIT` | `license` `MIT` |
 | Readme | A packed README with the same opener | `README.md` |
 
@@ -28,6 +31,35 @@ One sentence: what it is, for whom, and which Cratis product it belongs to - "<w
 Cratis Chronicle, the open-source event-sourcing database"). The text equals the README opener and
 the GitHub About text. Tags are specific ("event-sourcing", "cqrs", "dotnet"); never "utilities".
 
+## Repository and distribution surfaces
+
+- Set GitHub About's description to the same sentence, its website to the product docs page on
+  `https://www.cratis.io`, and topics to `cratis` plus accurate category terms.
+- Docker Hub's short description defines the image and names the parent product. Its full
+  description explains what it runs, how to start it and where the product docs live; keep the
+  definition and links aligned with the README. Do not add unsupported adoption or performance claims.
+- Analyzer `helpLinkUri` values link to the relevant diagnostic documentation on
+  `https://www.cratis.io`; keep the diagnostic path, not just the product homepage.
+- Template post-action messages and README footers link to the relevant docs on
+  `https://www.cratis.io`. Check nested READMEs and image READMEs, not just the repository root.
+- Preserve repository URLs as repository URLs. Do not rewrite schema identifiers, test fixtures,
+  negative examples or managed corpus copies while fixing user-facing links.
+
+## Verification
+
+Inspect effective NuGet properties on a packable project, including inherited values:
+
+```sh
+dotnet msbuild <packable.csproj> -getProperty:Authors -getProperty:Company -getProperty:Description -getProperty:PackageProjectUrl
+```
+
+A pass shows `Cratis` for Authors and Company, a nonempty parent-product definition and the
+existing product docs URL. Check npm `author`, `description`, `homepage` and `keywords` against the
+field map. Request each changed www URL and require HTTP 200 at the intended destination; fix
+broken paths rather than merely swapping hosts. Inspect GitHub About and Docker Hub metadata
+where available. Report remote metadata that cannot be checked or needs owner approval to change;
+a local README edit is not proof that a registry or repository setting changed.
+
 ## Pitfalls
 
 - An empty `Description`.

package/package/corpus/skills/cratis-discoverability/references/page-checklist.md

@@ -9,6 +9,7 @@
 - Landing pages
 - READMEs
 - Before publishing a site change
+- Docs-site guardrails
 
 ## Field targets
 
@@ -29,7 +30,7 @@ Lengths are targets, counted in characters including any site suffix.
 - [ ] Description written by hand; not the title, not another page's description.
 - [ ] The `description` answers what the page is or achieves in one self-contained sentence; the first paragraph does too on landing, index, glossary and README pages.
 - [ ] Canonical names; first mention uses the full "Cratis X" form.
-- [ ] Facts, numbers and comparisons carry a source or a date; nothing beyond the claim gate.
+- [ ] Facts, numbers and comparisons carry a source, and counts also carry a date; nothing beyond the claim gate.
 - [ ] Links have descriptive text. Root-relative inside the docs site, absolute
       `https://www.cratis.io/...` elsewhere.
 - [ ] Images have alt text (empty only when decorative) and sensible size.
@@ -86,3 +87,17 @@ Lengths are targets, counted in characters including any site suffix.
 - [ ] The content is in the raw HTML the server returns, not only rendered by JavaScript.
 - [ ] Internal links resolve; no apex `cratis.io` links.
 - [ ] A real HTTP 404 for unknown URLs; redirect stubs keep a canonical and stay out of the sitemap.
+
+## Docs-site guardrails
+
+- Keep missing-description and duplicate-title lint baselines at 0. Never raise a baseline to pass;
+  fix authored metadata or its generator and rerun the site's lint with no new exceptions.
+- Inspect rendered browser titles, not only frontmatter: retain the product name, add language
+  context for variants and distinguish repeated generic titles without changing page headings.
+- Measure UTF-8 bytes of `llms.txt` and `llms-small.txt`, including product/nested-product exports,
+  against the site's configured budgets. Keep `llms.txt` an index and `llms-small.txt` curated
+  starting points with one-line summaries, not a full inventory. Trim duplication and curation,
+  not human documentation or useful code examples. Do not raise budgets to hide growth.
+- Run the site's lint and enforced export-budget checks after its build; require exit 0 and
+  measured files within their limits. The built-site checker alone does not enforce these gates.
+  For export design, use **cratis-llm-friendly-documentation**.

package/package/corpus/skills/cratis-discoverability/references/structured-data.md

@@ -13,8 +13,17 @@
 - Markup describes what is visible on the page, and every date is a real one.
 - Add no `HowTo`. Add no new `FAQPage`; keep the visible question and answer text. Use `QAPage` only
   for real user questions and answers.
-- Do not name people (`Person`, `author` name) in structured data unless the owner has approved it.
-  Reference the organization by `@id`.
+- Use only public, owner-approved founder/company facts that are visible on the page. Founder
+  `Person` nodes may be linked from the organization with stable `@id`s and public profile links;
+  do not infer roles, employment or relationships from contributor accounts. Without this approval,
+  reference the organization by `@id` instead of naming a person.
+- Never add personal data or `Person` entities for community members, even if a profile displays
+  them. Do not serialize job titles, email, location, interests or CV details into JSON-LD.
+  Member profile and CV pages must emit `noindex`; keep them out of the sitemap. Do not apply
+  this policy to the community home or join page. Check rendered robots metadata or the
+  `X-Robots-Tag` header; blocking crawling alone does not establish `noindex`.
+- Shared guidance stays generic: no private/unannounced integration names, legal entity details
+  or factual counts copied from source material.
 - Do not add `offers`, an address or contact data without approval (see `SITE.md`).
 - Validate with the schema.org validator or Google's Rich Results Test. Invalid markup is worse than
   none. Static sites hand-write `<script type="application/ld+json">`; Astro sites generate it in
@@ -31,6 +40,7 @@
 | Blog post | `BlogPosting` (`datePublished`, `dateModified`, `publisher`, `image`) |
 | Repository or sample code | `SoftwareSourceCode` |
 | Legal pages | `WebPage` |
+| Member profiles and CV pages | no `Person` or personal structured data; `noindex` |
 | 404 and app hosts | none |
 
 ## Pattern

package/package/corpus/skills/cratis-discoverability/verification.json

@@ -1,13 +1,37 @@
 {
   "skill": "cratis-discoverability",
-  "input": "Run the pre-publish discoverability check on a new blog post, a package README and the package metadata for a Cratis library.",
+  "input": "Run the pre-publish discoverability check on entity facts and download claims, package/repo metadata, docs-site guardrails and founder/company or member profile structured data.",
   "fixtures": [],
   "assertions": [
     { "kind": "skill-contains", "value": "If a fix makes the page worse to read," },
     { "kind": "skill-contains", "value": "Add no `HowTo` and" },
-    { "kind": "skill-contains", "value": "Do not name people in structured data." },
+    { "kind": "skill-contains", "value": "never add personal data or `Person` entities for community members." },
     { "kind": "skill-contains", "value": "Apex `https://cratis.io/` links: the docs host is `https://www.cratis.io`." },
     { "kind": "skill-contains", "value": "no logo-only or metaphor opener" },
-    { "kind": "skill-contains", "value": "Padding to a word count: there is no minimum length" }
+    { "kind": "skill-contains", "value": "Padding to a word count: there is no minimum length" },
+    { "kind": "skill-contains", "value": "one sourced \"at a glance\" block" },
+    { "kind": "skill-contains", "value": "Downloads are never users or customers." },
+    { "kind": "skill-contains", "value": "Authors and Company are `Cratis`." },
+    { "kind": "skill-contains", "value": "never raise a baseline to pass." },
+    { "kind": "skill-contains", "value": "Member\nprofiles are `noindex`" },
+    { "kind": "skill-contains", "value": "Attach a source to every fact", "file": "references/facts-and-adoption.md" },
+    { "kind": "skill-contains", "value": "Never invent customers, user counts, benchmarks, certifications,", "file": "references/facts-and-adoption.md" },
+    { "kind": "skill-contains", "value": "Count entry packages\n   only", "file": "references/facts-and-adoption.md" },
+    { "kind": "skill-contains", "value": "include predecessor package names", "file": "references/facts-and-adoption.md" },
+    { "kind": "skill-contains", "value": "round down, never to nearest", "file": "references/facts-and-adoption.md" },
+    { "kind": "skill-contains", "value": "as of <month year>, across <named\n   registries>", "file": "references/facts-and-adoption.md" },
+    { "kind": "skill-contains", "value": "Do not add shared dependencies", "file": "references/facts-and-adoption.md" },
+    { "kind": "skill-contains", "value": "<Company>Cratis</Company>", "file": "references/package-metadata.md" },
+    { "kind": "skill-contains", "value": "https://www.cratis.io/<product>/", "file": "references/package-metadata.md" },
+    { "kind": "skill-contains", "value": "GitHub About", "file": "references/package-metadata.md" },
+    { "kind": "skill-contains", "value": "Docker Hub's short description", "file": "references/package-metadata.md" },
+    { "kind": "skill-contains", "value": "Analyzer `helpLinkUri`", "file": "references/package-metadata.md" },
+    { "kind": "skill-contains", "value": "Template post-action messages and README footers", "file": "references/package-metadata.md" },
+    { "kind": "skill-contains", "value": "lint baselines at 0", "file": "references/page-checklist.md" },
+    { "kind": "skill-contains", "value": "Measure UTF-8 bytes of `llms.txt` and `llms-small.txt`", "file": "references/page-checklist.md" },
+    { "kind": "skill-contains", "value": "retain the product name", "file": "references/page-checklist.md" },
+    { "kind": "skill-contains", "value": "public, owner-approved founder/company facts", "file": "references/structured-data.md" },
+    { "kind": "skill-contains", "value": "Never add personal data or `Person` entities for community members", "file": "references/structured-data.md" },
+    { "kind": "skill-contains", "value": "no private/unannounced integration names, legal entity details", "file": "references/structured-data.md" }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.97.1",
+  "version": "7.98.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [