[v1 scaffold · DRAFT] State of Equipment Management 2026 — hub, dynamic page, MDX, distribution materials#142
Draft
carlosvirreira wants to merge 5 commits into
Draft
Conversation
Foundation commit for the State of Equipment Management 2026 report scaffold. This is v1 infrastructure — the actual report content and hub/dynamic pages land in subsequent commits. src/lib/mdx.ts - Add "reports" to ContentType union. - Extend reading-time auto-calculation to reports (in addition to blog). src/lib/content/schema.ts - New "Reports" frontmatter block on Frontmatter interface. Optional fields capture the things that make an industry report citable: reportYear, dataWindowStart/End (ISO 8601), sampleSize (workspaces/ assets/countries/notes), pdfUrl, csvUrl, methodologyUrl, methodologyVersion, datasetKey, featured flag. - The methodology + sample-size fields are what journalists, analysts, and Wikipedia editors look at when deciding whether to cite. src/lib/seo.ts - Register "reports" in CONTENT_SEO so buildContentMetadata() handles /reports/* canonicals and OG metadata. - New reportJsonLd() returning Schema.org Report (more specific than Article — flags this as a research artifact, not a blog post). - New datasetJsonLd() returning Schema.org Dataset for the underlying aggregates. This is the killer schema for discovery: Google Dataset Search indexes it, and researchers/journalists find reports through it. License set to CC BY 4.0 — explicitly invites Wikipedia citation (their reuse policy requires CC-BY-or-equivalent). - temporalCoverage on Dataset uses ISO 8601 interval format (start/end) per Schema.org spec. src/components/mdx/citation-block.tsx (NEW) - Renders APA, MLA, and Chicago citation formats for the report. - Author-list formatter switches between style conventions (et al. for MLA/Chicago at 3+ authors; full list for APA). - Footer note advertises the CC BY 4.0 license with a direct link to the license terms. - Designed to be the last block on a report page — gives journalists, students, and Wikipedia editors a clean citation without leaving. src/components/mdx-content.tsx - Register CitationBlock in the MDX components map so it can be used directly in report MDX bodies. src/app/sitemap.ts - Add /reports to staticRoutes (priority 0.8 — annual reports are high-priority evergreen content). - Add a contentEntries() call for the "reports" type with yearly changeFrequency and 0.9 per-entry priority. Reports rarely change after publication but are heavily cited, so the high priority is intentional. Subsequent commits land the hub page (/reports), the dynamic /reports/[slug] page, the State of Equipment Management 2026 MDX, the typed data file, distribution materials, and an llms.txt update.
Second commit of the State of Equipment Management 2026 v1 scaffold. Foundation (content type registration + JSON-LD helpers + CitationBlock + sitemap) landed in 1d265b2. This commit adds the public-facing pages and the report content itself. src/app/(marketing)/reports/page.tsx (NEW) - Hub page at /reports. Hero, featured-report card (the 2026 edition), archive grid for future years, methodology footer note. - Emits CollectionPage JSON-LD with ItemList of all reports. - Featured selection: frontmatter `featured: true` wins; otherwise newest by date. Annual editions can swap featured easily. src/app/(marketing)/reports/[slug]/page.tsx (NEW) - Dynamic page for individual reports. Custom layout (does NOT use resolveLayout) because reports have a distinct hero shape: title + standfirst + byline + sample-size stats + PDF/CSV download CTAs. - Body rendered via shared MDXContent so prose styling stays consistent with blog/case-studies. - Footer cross-links back to /reports and to a Try-Shelf-free CTA. - Emits three JSON-LD entities per page: 1. BreadcrumbList (Home / Reports / Title) 2. Report (Schema.org Report — more specific than Article; flags the page as a research artifact for journalists / Wikipedia) 3. Dataset (the killer for Google Dataset Search discovery; includes temporalCoverage as ISO 8601 interval, CC BY 4.0 license, csvUrl as DataDownload distribution) content/reports/state-of-equipment-management-2026.mdx (NEW) - Full v1 prose scaffold for the 2026 report. ~3000 words across: executive summary, methodology, five findings (visibility, bookings, custody, audits, cost of disorder), per-industry cuts (education, IT, media, construction), top-performer behavioral patterns, limitations, about + citation block. - Every statistic is marked {{TODO: <stat_key>}} for the data team to replace from the extraction script output. - Methodology section is real, not placeholder — it's the trust signal that determines whether journalists and Wikipedia editors cite the report. Includes inclusion criteria, anonymization rules, definitions, confidence levels, reproducibility, and limitations. - Customer pull quotes are explicit {{TODO: outreach}} markers, NOT invented quotes attributed to real customers (avoids the worst possible failure mode for a report like this). - A publication note at the top warns editors to remove it before publishing. src/data/state-of-equipment-management-2026.ts (NEW) - Typed data structure that mirrors every stat referenced in the MDX. - Headline stats, per-section stats, industry cuts, top-performer patterns, customer quotes — each strongly typed with source (telemetry/survey/benchmark), confidence (high/medium/low), and free-form notes for the data team. - File header documents the data-team workflow: run extraction script in shelf.nu, copy values here, verify <StatBlock /> references resolve, upload CSV companion.\n- Quotes table flags `approved: false` until outreach confirmation — prevents accidentally publishing unauthorized customer attribution. Not in this commit (coming next): distribution materials (press release, share copy, email templates, citation guide) under content/reports/distribution/, llms.txt update to feature /reports, and the launch update entry.
Third commit of the State of Equipment Management 2026 v1 scaffold.
Adds the off-page distribution materials and a critical defensive
change on the report MDX itself.
content/reports/state-of-equipment-management-2026.mdx
- Added `seo.noindex: true` to the frontmatter. This is the single most
important defensive change in this PR: while the prose contains
{{TODO}} placeholder statistics, search engines must not index the
page. Without this flag, Google could crawl the draft, serve
placeholder text in search results, and contaminate the report's
reputation before launch. buildContentMetadata() reads `seo.noindex`
and emits `<meta name="robots" content="noindex,nofollow">`.
- The publication note at the top of the MDX now also reminds the
editor to flip noindex to false after data is plugged in and
editorial signs off.
content/reports/distribution/ (NEW directory, 6 files)
- README.md — explains the launch sequence, who owns what, and the
rules (no invented quotes, no invented stats, no missed embargo).
- press-release.md — embargoed press release draft. Lead paragraph
with the most-citable stat (custody gap), four bullet findings,
founder quote placeholder, methodology footer, About Shelf, contact.
Every {{TODO}} maps to a real stat key in src/data/.
- customer-email.md — launch-day customer email with three subject-
line options, preview text, body copy that respects the
anonymization promise ("Your data is not in there individually"),
segmentation notes for the email send (Team-tier only, suppress
active support tickets, Tuesday 10am local).
- press-pitch.md — pitch email template for individual journalists.
Per-publication customization slots, three findings to lead with,
embargo-aware delivery rules. Notes for the sender at the bottom.
- share-copy.md — LinkedIn (long post personal, short company page,
10-slide carousel), X (single, 7-tweet thread, pull-quote), Threads
variants. Rules at the bottom: numbers must match the report
exactly, no invented quotes, no link shorteners.
- wikipedia-citation.md — the highest-leverage distribution channel.
Explicit warning against COI editing from a Shelf account, the
correct Edit Request process, eight candidate articles in rough
order of likelihood, the pre-filled {{cite report}} template, and
the rules that determine whether Wikipedia editors accept the
citation or blacklist the domain.
Voice across all five distribution files: plain, benefit-led,
specific. No invented numbers — every quantified claim references
a {{TODO}} that resolves against src/data/state-of-equipment-
management-2026.ts. Quotes are explicit {{TODO: outreach for...}}
markers, never invented attribution.
Distribution files live under content/reports/distribution/ but
are NOT rendered as public pages — they're internal-only docs that
happen to live in the repo for version control alongside the report.
The /reports/[slug] dynamic page only renders MDX from
content/reports/*.mdx (not nested folders).
Next commit lands: llms.txt update (just the /reports hub, not the
specific 2026 report URL while it's noindexed) and the launch
update entry as a stub.
5 tasks
…ewrite)
Pivot per editorial review. The v1 scaffold was a thorough 30-stat
infrastructure piece; the editorial verdict was that it had no
quotable headline and would not earn citation. This commit cuts the
scope to 8 prioritized stats organized around a single viral headline:
the median workspace's dollar value of ghost assets.
src/data/state-of-equipment-management-2026.ts
- Trimmed from 30+ stats across six section blocks to 8 headline stats
organized as one viral lead + supporting stats + survey + dollar
variants. THE HEADLINE: ds_ghost_asset_dollar_value_median_workspace.
- Added `priorYearValue?: string` to ReportStat so the 2027 edition
can render year-over-year trend lines without restructuring.
- Added `MiniCaseStudy` and `ExternalBenchmark` typed structures so
the report has structured customer narrative + structured external
comparison.
- Removed: industryCuts (deferred to 2027 with more data), topPerformer
patterns (admitted-correlations, no causal claim — moved to a future
blog post if interesting), demographic stats (median assets, median
users), feature-adoption rates dressed as findings (% with category,
% with custom fields), peak-day, lead-time-days.
content/reports/state-of-equipment-management-2026.mdx
- Complete rewrite around the ghost-assets-in-dollars headline. Lead
paragraph leads with the dollar figure. Five executive-summary
bullets, dollar-prefixed where applicable.
- Reduced from ~3000 words to ~2000 words. Tighter. Five focused
finding sections instead of seven.
- THE GHOST ASSET DEEP DIVE is now its own section — the precise
definition (4 clauses), the dollar mechanic with the Asset.valuation
coverage caveat, and the four downstream impacts (budgets,
depreciation, insurance, headcount ratios).
- Three <MiniCaseStudy> blocks interspersed with their illustrating
findings (ghost assets / audit cadence / recovery story).
- New "operational tax" section that pairs telemetry with the survey
data — the "why" alongside the "what".
- New "How this compares to the industry" callout for the one external
benchmark.
- Methodology updated to include the Asset.valuation coverage caveat
and the survey methodology (n=200, distribution, anonymization).
- noindex: true preserved (still in scaffold state).
content/reports/distribution/press-release.md
- Headline rewritten around the dollar figure:
"New Shelf industry report finds the median organization has
{{$X,XXX}} of equipment on the books but missing from audits"
- Subhead and lead paragraph pivot to ghost-assets framing. "Ghost
assets" introduced as the report's branded term in the first
three sentences.
- Founder quote placeholder rewritten to lead with the dollar number.
- Methodology footer updated to disclose Asset.valuation coverage
+ survey methodology.
content/reports/distribution/share-copy.md
- All LinkedIn / X / Threads variants rewritten around the dollar
headline. Single launch tweet, 6-tweet thread, pull-quote tweet,
carousel structure all pivoted.
- "Ghost assets is the phrase to lead with" rule added — consistency
across channels builds the term as Shelf's IP and earns the
Wikipedia article on "ghost asset" eventually.
content/reports/research-inputs/README.md (NEW)
- Explains why telemetry + survey + external benchmark is the
minimum-viable shape for an industry report worth citing. Timeline,
ownership, sequencing.
content/reports/research-inputs/survey-design.md (NEW)
- Full 5-question survey design with question-by-question rationale,
where each result lands in the report, tooling recommendations
(Typeform / Sprig / built-in), distribution channels, anonymization
rules, demographic capture from workspace metadata, implementation
checklist, cost estimate (~$0–$50/mo + 8 marketing hours), and
"what good looks like" success criteria.
- Q1 (hours lost per month) produces the survey's headline stat that
pairs with the dollar headline from telemetry.
- Q3 (open-ended single pain) is the goldmine for quotable themes.
content/reports/research-inputs/external-benchmarks.md (NEW)
- Five categories of candidate third-party benchmarks to research
(insurance industry, trade associations, academic research,
government audits, consulting firms) with specific source
recommendations within each (Marsh, Aon, ARMA, GAO, MIT CISR, etc).
- Selection criteria: independent, public, methodologically
transparent, recent, quotable, topic-adjacent.
- Decision template for the founder to fill in for the chosen
candidate. Honest fallback if no good benchmark exists.
Companion shelf.nu PR (#2570) will be updated in the next commit:
- queries/disorder.ts gains the three dollar-value stat shapes.
- output-schema.ts gains priorYearValue + dollarValue fields.
- queries/industries.ts and queries/top-performers.ts are commented
out in the orchestrator (kept in repo for future restoration).
- README + methodology.md updated to reflect the trimmed scope.
…rsal telemetry) Second editorial pivot per CEO risk review. The v1.1 ghost-asset headline depended on the Audits add-on — a paid feature with bounded adoption. If audits adoption is below ~20% of Team workspaces, the "median workspace" framing is dishonest (it's really "median of an audit-enabled minority"). The new headline uses universal telemetry that fires for every Shelf customer: idle assets, defined via ActivityEvent. No paid-feature dependency. The headline survives even if audits adoption is low. Ghost-asset stats are not deleted — they are demoted to a properly- qualified "audit-enabled subset" section. The narrative is honest: "For the X% of Team workspaces that ran at least one completed audit..." rather than "median workspace." src/data/state-of-equipment-management-2026.ts - Headline stat changed to ds_idle_asset_dollar_value_median_workspace (was ds_ghost_asset_dollar_value_median_workspace). - Added ds_idle_asset_rate (% companion). - Added bk_pct_returned_late (booking-using subset; the cascade event). - Demoted ds_ghost_asset_rate and au_pct_audited_assets_missing to qualified subset stats, with a new `qualification?: string` field on ReportStat that the MDX prepends to any prose using the stat. - Added `adoptionThresholds` block to reportMetadata: explicit numerical thresholds for audits-enabled, audits-run, bookings-active, and Asset.valuation coverage. Below threshold = stat is dropped or converted to percentage-only. This is the risk discipline the CEO asked for. content/reports/state-of-equipment-management-2026.mdx - Full rewrite around the idle-asset headline. Standfirst leads with the dollar figure. Executive summary reordered: idle is #1, late returns is #3, audit-subset is #5 (qualified). - THE IDLE-ASSET DEEP DIVE is the new prominent section — definition in three clauses, financial impact in four bullets (procurement waste / depreciation against unused / insurance overpayment / headcount ratios), explicit comparison to traditional loss-rate framing. - Renamed "Finding 5: For the audit-enabled subset" — heavily qualified, smaller scope, explicitly NOT presented as platform median. - New "Late return problem" section using bk_pct_returned_late. - Methodology section adds an explicit "Risk disclosures" block: feature-adoption risk, Asset.valuation coverage, cohort-size enforcement, survey response rate. This is the trust-signal that earns the citation. - "Idle asset" gets a precise three-clause definition matching the query in shelf.nu/queries/disorder.ts. - Limitations section flags feature-adoption variance and survey size caveat honestly. content/reports/distribution/press-release.md - Headline pivots to idle-asset dollar figure. - Lead paragraph reframes around dead capital, depreciation, insurance. - Audit-subset findings get an explicit qualification paragraph noting the subset cohort, not platform median. - Founder quote placeholder updated. content/reports/distribution/share-copy.md - All LinkedIn / X / Threads variants rewritten around idle-asset headline. "Idle assets" becomes the branded term across channels (replaces "ghost assets" as the lead term). - New rule: audit-specific stats must always carry the qualifier "for audit-enabled workspaces" in any social copy. Unqualified posting misrepresents the cohort. Companion shelf.nu PR (#2570) is updated in the next commit: - New `probe.ts` feature-adoption probe that the data team runs FIRST to verify the cohort math works for each stat before implementing queries. - queries/disorder.ts pivoted so idle stats are primary. - queries/bookings.ts un-deferred for the bk_pct_returned_late stat. - methodology.md updated with the risk-disclosure block.
Merged
7 tasks
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.
What this is
V1 scaffold for The State of Equipment Management 2026 — Shelf's inaugural annual industry report.
This is the marketing-site half of a two-repo effort. A companion PR on
shelf-nu/shelf.nuwill scaffold the data-extraction kit (SQL queries, anonymization rules, methodology doc, CLI runner) the data team uses to produce the underlying numbers.Both PRs are draft. Both should stay draft until the data team has run the extraction, the {{TODO}} placeholders here are real numbers, customer quote outreach is done, the OG image is designed, and editorial has signed off.
Hypothesis
Industry reports are the single highest-multiplier content asset a B2B company can ship — they compound in three ways that nothing else does:
The compounding mechanism is original first-party data nobody else has. Vendor surveys don't compound. Telemetry-backed numbers with open methodology do.
What's in this PR
3 commits, 13 files under
claude/state-of-equipment-management-2026:1d265b2"reports"as a new MDX content type; newreportJsonLd()(Schema.orgReport) anddatasetJsonLd()(Schema.orgDataset— discoverable in Google Dataset Search) helpers; newCitationBlockMDX component rendering APA/MLA/Chicago citations; sitemap registration8042527/reports+ dynamic page at/reports/[slug]; full 3000-word report MDX draft with placeholder stats clearly marked{{TODO: <stat_key>}}; strongly-typedsrc/data/state-of-equipment-management-2026.tsdata file withReportStat,IndustryCut,TopPerformerPattern,ReportQuotetypesa023d65content/reports/distribution/(press release, customer email, press pitch, share copy, Wikipedia citation guide, README); defensiveseo.noindex: trueon the report MDX — see Critical safety belowCritical safety: the report is
noindex: trueThe report MDX contains
{{TODO}}placeholder statistics throughout. If Google crawled this page in its current state, it would index "the median Shelf workspace tracks{{TODO: median_assets_per_workspace}}assets" — and that text would appear in search results until the next recrawl after launch. That would be catastrophic for the report's reputation.The MDX frontmatter sets
seo.noindex: true.buildContentMetadata()emits<meta name="robots" content="noindex,nofollow">for the page. The page is still in the sitemap and ingetAllContent("reports")(the hub will display it), but search engines will not index it.Before launch, the data team flips
noindex: true→noindex: falsein the frontmatter. This is documented in two places:content/reports/distribution/README.mdlaunch sequenceDecisions made unilaterally
/reports/[slug]with a hub at/reports. The slug includes the year so 2027/2028 editions are simple/reports/state-of-equipment-management-2027. The hub picks featured viafeatured: truefrontmatter, falling back to newest by date.temporalCoverage("2025-05-01/2026-04-30") per Schema.org spec.{{TODO: outreach for...}}markers, NOT invented quotes attributed to real customers. Failure mode I deliberately avoided. The data team has to do real customer outreach before any quote appears.{{TODO}}until the data team plugs them in. No "placeholder reasonable-sounding numbers" — those would calcify into accidentally-real claims. Explicit sentinels force the data team to replace every one.[slug]page renders the hero + body + footer directly with full control over typography. The MDX body uses the standardMDXContentstyling so prose stays consistent with blog/case-studies.<StatBlock />. If editorial wants charts later, they can be added as a separate<BarChart />component without churn here.What v1 is NOT
{{TODO}}sentinel. The data team runs the extraction script in the companion shelf.nu PR.{{TODO: outreach}}markers. Real quotes need real permission./public/images/reports/state-of-equipment-management-2026/cover.png(referenced in frontmatter)./public/reports/state-of-equipment-management-2026.{pdf,csv}— files need to be uploaded.noindexand the data is placeholder. Once real data is in, llms.txt should promote the report to Key Links.distribution/wikipedia-citation.md. The actual edit requests happen 2-4 weeks after launch, per the guide's process.Two-repo handoff
The companion PR on
shelf-nu/shelf.nuwill scaffold:apps/webapp/scripts/state-of-em-2026/with a CLI runner (tsx-invoked, production guard, dotenv, JSON output)methodology.mdmirroring the report's methodology sectionpackage.jsonscript wiring at both monorepo levelsThe data team's workflow once both PRs land:
pnpm webapp:report:state-of-em-2026 --i-know-what-im-doingon a read-replica (or prod with the guard flag)src/data/state-of-equipment-management-2026.tson the website-v2 branch<StatBlock />in the MDX still resolvespublic/reports/{{TODO: outreach for...}}placeholderspublic/images/reports/state-of-equipment-management-2026/cover.pngseo.noindex: true→falsein the MDX frontmatterFile tree (this PR)
Test plan
pnpm typecheckpassespnpm buildpasses — particularly that the newFrontmatterfields don't trip the type-checker, the new MDX components register, and the dynamic/reports/[slug]route generates static params/reports— hub page renders, featured card shows the 2026 report, methodology footer is visible/reports/state-of-equipment-management-2026— page renders, hero shows title + standfirst + sample-size cards + download CTAs, body renders MDX with all{{TODO}}sentinels visible (this is correct for v1),<CitationBlock />renders at the bottom with three citation formats and CC BY 4.0 footer/reports/state-of-equipment-management-2026. Confirm three<script type="application/ld+json">blocks:BreadcrumbList,Report,Dataset<meta name="robots" content="noindex,nofollow">is in the page head (the noindex safety)/sitemap.xml—/reportsis listed;/reports/state-of-equipment-management-2026IS in the sitemap (intentional — Google still discovers the URL even with noindex; flipping noindex later means immediate indexing)Handoff checklist for the data team
When the shelf.nu extraction PR is ready and the script has been run:
{{TODO}}incontent/reports/state-of-equipment-management-2026.mdxwith a real value"{{TODO}}"insrc/data/state-of-equipment-management-2026.tsreportMetadata.sampleSizewith real workspace/asset/country countsreportMetadata.publishedAtwith the real publication datepublic/reports/state-of-equipment-management-2026.pdf(designer output)public/reports/state-of-equipment-management-2026.csv(script CSV output)public/images/reports/state-of-equipment-management-2026/cover.png(designer output)<PullQuote />blocks in the MDX with approved quotesquotesarray in the data file withapproved: trueper quoteseo.noindex: true→falsein the MDX frontmattercontent/reports/distribution/README.mdlaunch sequencewikipedia-citation.mdpublic/llms.txtto promote the report to Key Links (intentionally skipped in this PR)This PR remains in draft until all of the above is done.
Generated by Claude Code