Skip to content

Commit 08da53d

Browse files
richlanderclaude
andcommitted
Reorder reference.md sections for better learning flow
Move Schema Examples before detailed CVE workflows so readers see concrete schema structure before navigating complex analyses. New order: Entry Points → Common Workflows → Discovering Resource Schema → Schema Examples → CVE Analysis Workflows → Breaking Changes Workflow → Quick Queries → References 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 1c14d83 commit 08da53d

File tree

1 file changed

+43
-43
lines changed

1 file changed

+43
-43
lines changed

llms/reference.md

Lines changed: 43 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -33,49 +33,6 @@ Reference:
3333
| SDK downloads | `10.0/sdk/index.json` |
3434
| OS support | `10.0/manifest.json``_links["supported-os-json"].href` |
3535

36-
## CVE Analysis Workflows
37-
38-
### Version-Centric (for version/patch queries)
39-
40-
1. GET `index.json` → navigate to major version (e.g., `10.0/index.json`)
41-
2. View embedded CVE summaries in `_embedded.releases[]` where `security: true`
42-
3. Find latest security patch: `_links["latest-security"].href`
43-
4. Navigate to patch index → **full details in `_embedded.disclosures[]`**
44-
5. For package-level details or commit diffs: `_links["cve-json"].href`
45-
6. **Always ask**: "Would you like inline diffs for these fixes?"
46-
7. If yes: **Fetch immediately** — use `commits[hash].url` (already `.diff` format)
47-
48-
### Time-Centric (for date-range queries)
49-
50-
1. GET `timeline/index.json` → navigate to year → navigate to month
51-
2. View CVEs inline: `_embedded.disclosures[]` has full details
52-
3. For package-level details: `_links["cve-json"].href`
53-
4. **Always ask**: "Would you like inline diffs for these fixes?"
54-
5. If yes: **Fetch immediately** — firewall or domain restrictions may block later access
55-
56-
### Diff Retrieval (IMPORTANT)
57-
58-
Always fetch all provided diff URLs immediately when analyzing CVEs. Do not defer.
59-
60-
GitHub commit URLs support multiple formats:
61-
- **`.diff`** — Raw unified diff (best for code analysis)
62-
- **`.patch`** — Git patch with commit message (best for context)
63-
- **(no extension)** — Web view (for humans)
64-
65-
The graph provides `.diff` URLs by default in `commits[hash].url`.
66-
67-
## Breaking Changes Workflow
68-
69-
1. GET `index.json` → navigate to major version
70-
2. Follow `_links["compatibility-json"].href`
71-
3. Use pre-computed rollups for overview:
72-
- `categories` — list of all categories
73-
- `impact_breakdown` — count by impact level
74-
- `type_breakdown` — count by change type
75-
4. Filter `breaks[]` by `category`, `impact`, or `type`
76-
5. For migration guidance: check `required_action` field
77-
6. For raw documentation: filter `references[]` by `type: "documentation-source"`
78-
7936
## Discovering Resource Schema
8037

8138
HAL resources are self-describing. If you're unsure what's available, inspect the resource:
@@ -515,6 +472,49 @@ The CVE JSON file provides full details and pre-computed query dictionaries:
515472
}
516473
```
517474

475+
## CVE Analysis Workflows
476+
477+
### Version-Centric (for version/patch queries)
478+
479+
1. GET `index.json` → navigate to major version (e.g., `10.0/index.json`)
480+
2. View embedded CVE summaries in `_embedded.releases[]` where `security: true`
481+
3. Find latest security patch: `_links["latest-security"].href`
482+
4. Navigate to patch index → **full details in `_embedded.disclosures[]`**
483+
5. For package-level details or commit diffs: `_links["cve-json"].href`
484+
6. **Always ask**: "Would you like inline diffs for these fixes?"
485+
7. If yes: **Fetch immediately** — use `commits[hash].url` (already `.diff` format)
486+
487+
### Time-Centric (for date-range queries)
488+
489+
1. GET `timeline/index.json` → navigate to year → navigate to month
490+
2. View CVEs inline: `_embedded.disclosures[]` has full details
491+
3. For package-level details: `_links["cve-json"].href`
492+
4. **Always ask**: "Would you like inline diffs for these fixes?"
493+
5. If yes: **Fetch immediately** — firewall or domain restrictions may block later access
494+
495+
### Diff Retrieval (IMPORTANT)
496+
497+
Always fetch all provided diff URLs immediately when analyzing CVEs. Do not defer.
498+
499+
GitHub commit URLs support multiple formats:
500+
- **`.diff`** — Raw unified diff (best for code analysis)
501+
- **`.patch`** — Git patch with commit message (best for context)
502+
- **(no extension)** — Web view (for humans)
503+
504+
The graph provides `.diff` URLs by default in `commits[hash].url`.
505+
506+
## Breaking Changes Workflow
507+
508+
1. GET `index.json` → navigate to major version
509+
2. Follow `_links["compatibility-json"].href`
510+
3. Use pre-computed rollups for overview:
511+
- `categories` — list of all categories
512+
- `impact_breakdown` — count by impact level
513+
- `type_breakdown` — count by change type
514+
4. Filter `breaks[]` by `category`, `impact`, or `type`
515+
5. For migration guidance: check `required_action` field
516+
6. For raw documentation: filter `references[]` by `type: "documentation-source"`
517+
518518
## CVE JSON Quick Queries
519519

520520
```bash

0 commit comments

Comments
 (0)