Skip to content

Commit 2655242

Browse files
author
trucore-ai
committed
docs(agents): complete frontmatter coverage and add metadata schema reference
1 parent a59ae36 commit 2655242

3 files changed

Lines changed: 174 additions & 0 deletions

File tree

‎docs/metadata-schema.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: Metadata & Frontmatter Schema Reference
3+
summary: Field definitions, examples, and rules for metadata used across TruCore-site pages and atf-spec docs.
4+
layer: public
5+
audience: human
6+
status: guide
7+
product_area: [documentation, governance]
8+
related_pages: [docs/CONTENT_MAP.md]
9+
---
10+
11+
# Metadata & Frontmatter Schema Reference
12+
13+
This document defines the metadata and frontmatter schemas used across TruCore documentation surfaces. Contributors should follow these patterns when adding or updating docs.
14+
15+
---
16+
17+
## 1. atf-spec Frontmatter (Markdown files)
18+
19+
All public spec and docs files in `atf-spec` use YAML frontmatter.
20+
21+
### Fields
22+
23+
| Field | Type | Required | Description |
24+
| --- | --- | --- | --- |
25+
| `title` | string | yes | Human-readable page title. |
26+
| `summary` | string | yes | One-sentence description of the document's purpose. |
27+
| `layer` | `"public"` | yes | Always `public` for files in this repo. |
28+
| `audience` | `"human"` \| `"agent"` \| `"both"` | yes | Primary audience. Use `both` for spec docs consumed by humans and machines. |
29+
| `status` | `"spec"` \| `"guide"` \| `"tutorial"` \| `"canonical"` \| `"map"` | yes | Document type. See status values below. |
30+
| `product_area` | string[] | yes | One or more product areas (e.g., `[receipts, verification]`). |
31+
| `related_pages` | string[] | no | Relative paths to related files within the repo. |
32+
| `site_ref` | string | no | Corresponding TruCore-site route (e.g., `/docs/receipt-specification-v1`). |
33+
34+
### Status values
35+
36+
| Value | Use when |
37+
| --- | --- |
38+
| `spec` | Normative specification document (receipt schema, verification, architecture). |
39+
| `guide` | Explanatory or how-to content for developers. |
40+
| `tutorial` | Step-by-step walkthrough (hello-world-bot). |
41+
| `canonical` | Authoritative reference (content map, glossary). |
42+
| `map` | Navigation or index document. |
43+
44+
### Example: Public spec doc
45+
46+
```yaml
47+
---
48+
title: ATF Receipt Specification
49+
summary: Normative receipt schema — fields, types, deterministic content_hash computation, and verification rules.
50+
layer: public
51+
audience: both
52+
status: spec
53+
product_area: [receipts, verification]
54+
site_ref: /docs/receipt-specification-v1
55+
---
56+
```
57+
58+
### Example: Public tutorial
59+
60+
```yaml
61+
---
62+
title: Hello-World Bot
63+
summary: Side-by-side Python scripts showing an unprotected bot vs an ATF-protected bot.
64+
layer: public
65+
audience: human
66+
status: tutorial
67+
product_area: [onboarding, integration]
68+
site_ref: /docs/hello-world-bot
69+
---
70+
```
71+
72+
---
73+
74+
## 2. TruCore-site Page Metadata (Next.js `Metadata` export)
75+
76+
All public `page.tsx` files under `app/docs/` export a `Metadata` object.
77+
78+
### Fields
79+
80+
| Field | Required | Description |
81+
| --- | --- | --- |
82+
| `title` | yes | Page title with `\| TruCore` or `\| TruCore ATF` suffix. |
83+
| `description` | yes | Factual, page-specific description (1–2 sentences). |
84+
| `keywords` | yes | Array of 5–10 relevant search terms. |
85+
| `openGraph.title` | yes | Same as or shortened version of `title`. |
86+
| `openGraph.description` | yes | Same as or shortened version of `description`. |
87+
| `openGraph.url` | yes | Canonical URL (`https://trucore.xyz/docs/{slug}`). |
88+
| `openGraph.images` | yes | `["/opengraph-image"]` unless a page-specific OG image exists. |
89+
| `twitter.card` | yes | Always `"summary_large_image"`. |
90+
| `twitter.title` | yes | Same as `openGraph.title`. |
91+
| `twitter.description` | yes | Same as or shortened version of `openGraph.description`. |
92+
| `twitter.images` | yes | Same as `openGraph.images`. |
93+
| `alternates.canonical` | yes | Canonical URL matching `openGraph.url`. |
94+
| `robots` | no | Override only when needed (e.g., `{ index: true, follow: true }`). |
95+
96+
### Example: Public docs page
97+
98+
```typescript
99+
export const metadata: Metadata = {
100+
title: "Getting Started | TruCore ATF",
101+
description:
102+
"Create an account, get an API key, and protect your first trade with ATF in minutes.",
103+
keywords: [
104+
"ATF getting started",
105+
"agent transaction firewall",
106+
"API key setup",
107+
"first protected trade",
108+
"developer onboarding",
109+
"TruCore ATF",
110+
],
111+
openGraph: {
112+
title: "Getting Started | TruCore ATF",
113+
description:
114+
"Create an account, get an API key, and protect your first trade with ATF in minutes.",
115+
url: "https://trucore.xyz/docs/getting-started",
116+
images: ["/opengraph-image"],
117+
},
118+
twitter: {
119+
card: "summary_large_image",
120+
title: "Getting Started | TruCore ATF",
121+
description:
122+
"Create an account, get an API key, and protect your first trade with ATF in minutes.",
123+
images: ["/opengraph-image"],
124+
},
125+
alternates: { canonical: "https://trucore.xyz/docs/getting-started" },
126+
};
127+
```
128+
129+
---
130+
131+
## 3. Rules
132+
133+
### Public vs authenticated docs
134+
135+
- **Public pages** (`app/docs/*`): always include full metadata (OG, twitter, keywords, canonical).
136+
- **Authenticated pages** (`app/docs/guide/*`): minimal metadata only. Do not add OG/twitter/canonical — these pages are behind auth and should not appear in search or social previews.
137+
- **Public discovery files** (`llms.txt`, `sitemap.ts`, `atf.json`): never reference authenticated pages.
138+
139+
### Title conventions
140+
141+
- TruCore-site: append `| TruCore` or `| TruCore ATF` to titles.
142+
- atf-spec: use the document's natural title without site branding.
143+
144+
### Canonical URLs
145+
146+
- Always use `https://trucore.xyz/docs/{slug}` for TruCore-site pages.
147+
- For atf-spec, use `site_ref` to point to the corresponding TruCore-site page when one exists.
148+
149+
### Keywords
150+
151+
- 5–10 terms per page.
152+
- Include the page's primary topic, ATF-specific terminology, and "TruCore ATF".
153+
- Do not stuff keywords — keep them relevant to the page content.

‎spec/examples.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
---
2+
title: ATF Receipt Examples
3+
summary: Illustrative receipt examples for reference and testing — minimal, enriched, and denied decision variants.
4+
layer: public
5+
audience: both
6+
status: spec
7+
product_area: [receipts, verification]
8+
related_pages: [spec/receipt.md, spec/verification.md]
9+
site_ref: /docs/receipt-specification-v1
10+
---
11+
112
# ATF Receipt Examples
213

314
This document provides illustrative receipt examples for reference and testing. These examples demonstrate the receipt structure defined in [spec/receipt.md](receipt.md) and the verification procedure described in [spec/verification.md](verification.md).

‎spec/redaction-policy.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,13 @@
1+
---
2+
title: Redaction Policy
3+
summary: Disclosure-minimization principles for ATF public specification — what is published, what is omitted, and why.
4+
layer: public
5+
audience: human
6+
status: spec
7+
product_area: [governance, security]
8+
site_ref: /docs/atf-architecture
9+
---
10+
111
# Redaction Policy
212

313
This document describes the disclosure-minimization principles applied to the ATF public specification. It is intended for contributors, reviewers, and anyone evaluating the scope of material published in this repository.

0 commit comments

Comments
 (0)