Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion CONTENT_GAPS_ANALYSIS.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ High-impact surfaces requiring continuous maintenance:

A tutorial track is considered production-ready when:

- it has `index.md` with valid local links
- it has `README.md` with valid local links
- it has a coherent numbered chapter sequence
- its summary and snapshot language are not stale or placeholder quality
- it passes repository docs health checks
2 changes: 1 addition & 1 deletion TUTORIAL_STRUCTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This file defines the canonical tutorial layout and current structure status.

```text
tutorials/<tutorial-name>/
index.md
README.md
01-*.md
02-*.md
...
Expand Down
102 changes: 51 additions & 51 deletions discoverability/query-coverage.json

Large diffs are not rendered by default.

102 changes: 51 additions & 51 deletions discoverability/query-hub.md

Large diffs are not rendered by default.

234 changes: 117 additions & 117 deletions discoverability/search-intent-map.md

Large diffs are not rendered by default.

382 changes: 191 additions & 191 deletions discoverability/tutorial-directory.md

Large diffs are not rendered by default.

764 changes: 382 additions & 382 deletions discoverability/tutorial-index.json

Large diffs are not rendered by default.

382 changes: 191 additions & 191 deletions discoverability/tutorial-itemlist.schema.json

Large diffs are not rendered by default.

382 changes: 191 additions & 191 deletions llms-full.txt

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion scripts/add_index_navigation_backlinks.py
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
import re
from pathlib import Path

INDEX_NAME = "index.md"
INDEX_NAME = "README.md"
NAV_HEADING = "## Navigation & Backlinks"
GENERATED_MARKER = "*Generated by [AI Codebase Knowledge Builder]"
NUMBERED_FILE_RE = re.compile(r"^([0-9]{2,})[-_].+\.md$")
Expand Down
2 changes: 1 addition & 1 deletion scripts/apply_pocketflow_style_pass.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
import re
from pathlib import Path

INDEX_NAME = "index.md"
INDEX_NAME = "README.md"
NUMBERED_FILE_RE = re.compile(r"^([0-9]{2,})[-_].+\.md$")
LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
GEN_FOOTER = (
Expand Down
2 changes: 1 addition & 1 deletion scripts/check_index_format_v2.py
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,7 @@ def main() -> int:
args = parser.parse_args()

root = Path(args.root).resolve()
index_paths = sorted((root / "tutorials").glob("*/index.md"))
index_paths = sorted((root / "tutorials").glob("*/README.md"))

opted_in: list[Path] = []
failures: list[tuple[Path, list[str]]] = []
Expand Down
2 changes: 1 addition & 1 deletion scripts/clean_source_references.py
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ def main() -> int:

changed_files = 0
for tutorial_dir in sorted(p for p in tutorials.iterdir() if p.is_dir()):
idx = tutorial_dir / "index.md"
idx = tutorial_dir / "README.md"
if not idx.is_file():
continue
text = read(idx)
Expand Down
4 changes: 2 additions & 2 deletions scripts/contextualize_chapter_sections.py
Original file line number Diff line number Diff line change
Expand Up @@ -80,7 +80,7 @@ def slug_phrase(text: str) -> str:
def chapter_files(tutorial_dir: Path) -> list[Path]:
out: list[tuple[int, str, Path]] = []
for path in tutorial_dir.glob("*.md"):
if path.name == "index.md":
if path.name == "README.md":
continue
match = NUMBERED_FILE_RE.match(path.name)
if not match:
Expand Down Expand Up @@ -296,7 +296,7 @@ def main() -> int:
chapter_changed = 0

for tutorial_dir in sorted(p for p in tutorials_root.iterdir() if p.is_dir()):
index_path = tutorial_dir / "index.md"
index_path = tutorial_dir / "README.md"
if not index_path.is_file():
continue
index_text = read_text(index_path)
Expand Down
2 changes: 1 addition & 1 deletion scripts/deepen_v2_chapters.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
import re
from pathlib import Path

INDEX_FILE = "index.md"
INDEX_FILE = "README.md"
DEPTH_MARKER = "<!-- depth-expansion-v2 -->"
NUMBERED_FILE_RE = re.compile(r"^([0-9]{2,})[-_].+\.md$")
LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
Expand Down
6 changes: 3 additions & 3 deletions scripts/docs_health.py
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,7 @@ def classify_tutorial_structure(root: Path) -> dict:
missing_index: list[str] = []

for tutorial_dir in sorted([p for p in tutorials_dir.iterdir() if p.is_dir()]):
has_index = (tutorial_dir / "index.md").is_file()
has_index = (tutorial_dir / "README.md").is_file()
top_level_count = len(list(tutorial_dir.glob(NUMBERED_MD_PATTERN)))
docs_count = 0
docs_dir = tutorial_dir / "docs"
Expand Down Expand Up @@ -157,7 +157,7 @@ def classify_tutorial_structure(root: Path) -> dict:
def collect_placeholder_summaries(root: Path) -> list[str]:
tutorials_dir = root / "tutorials"
matches: list[str] = []
for index_file in sorted(tutorials_dir.glob("*/index.md")):
for index_file in sorted(tutorials_dir.glob("*/README.md")):
text = index_file.read_text(encoding="utf-8", errors="ignore")
if PLACEHOLDER_SUMMARY in text:
matches.append(index_file.relative_to(root).as_posix())
Expand Down Expand Up @@ -211,7 +211,7 @@ def main() -> int:
print(link.as_tsv())

if structure_report["missing_index"]:
print("\nTutorial directories missing index.md:")
print("\nTutorial directories missing README.md:")
for item in structure_report["missing_index"]:
print(item)

Expand Down
8 changes: 4 additions & 4 deletions scripts/generate_discoverability_assets.py
Original file line number Diff line number Diff line change
Expand Up @@ -470,15 +470,15 @@ def infer_intent_signals(title: str, summary: str, cluster: str) -> list[str]:
def tutorial_dirs(root: Path) -> Iterable[Path]:
tutorials_root = root / TUTORIALS_DIR
for path in sorted([p for p in tutorials_root.iterdir() if p.is_dir()], key=lambda p: p.name):
if (path / "index.md").is_file():
if (path / "README.md").is_file():
yield path


def build_records(root: Path) -> list[dict]:
records: list[dict] = []

for tdir in tutorial_dirs(root):
index_path = tdir / "index.md"
index_path = tdir / "README.md"
raw = index_path.read_text(encoding="utf-8", errors="ignore")
body = strip_frontmatter(raw)

Expand All @@ -497,9 +497,9 @@ def build_records(root: Path) -> list[dict]:
"title": title,
"summary": summary,
"path": rel_dir,
"index_path": f"{rel_dir}/index.md",
"index_path": f"{rel_dir}/README.md",
"repo_url": f"https://github.com/johnxie/awesome-code-docs/tree/main/{rel_dir}",
"file_url": f"https://github.com/johnxie/awesome-code-docs/blob/main/{rel_dir}/index.md",
"file_url": f"https://github.com/johnxie/awesome-code-docs/blob/main/{rel_dir}/README.md",
"keywords": keywords,
"cluster": cluster,
"intent_signals": intent_signals,
Expand Down
2 changes: 1 addition & 1 deletion scripts/generate_tutorial_manifest.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@


def tutorial_record(root: Path, tutorial_dir: Path) -> dict:
has_index = (tutorial_dir / "index.md").is_file()
has_index = (tutorial_dir / "README.md").is_file()
top_level_files = sorted(tutorial_dir.glob(NUMBERED_MD_PATTERN))
docs_dir = tutorial_dir / "docs"
docs_files = sorted(docs_dir.glob(NUMBERED_MD_PATTERN)) if docs_dir.exists() else []
Expand Down
2 changes: 1 addition & 1 deletion scripts/release_claims_audit.py
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,7 @@ def main() -> int:
parser.add_argument(
"--targets",
nargs="*",
default=["tutorials/*/index.md"],
default=["tutorials/*/README.md"],
help="Glob patterns (relative to repo root) to scan",
)
parser.add_argument("--json-output", help="Optional JSON output path")
Expand Down
2 changes: 1 addition & 1 deletion scripts/staleness_audit.py
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
DEFAULT_TARGET_GLOBS = (
"README.md",
"tutorials/README.md",
"tutorials/*/index.md",
"tutorials/*/README.md",
"categories/*.md",
"discoverability/*.md",
"CONTENT_GAPS_ANALYSIS.md",
Expand Down
6 changes: 3 additions & 3 deletions scripts/update_repo_status_docs.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

def collect_tutorial_dirs(root: Path) -> list[Path]:
tutorials_root = root / "tutorials"
return sorted([p for p in tutorials_root.iterdir() if p.is_dir() and (p / "index.md").is_file()])
return sorted([p for p in tutorials_root.iterdir() if p.is_dir() and (p / "README.md").is_file()])


def chapter_count(tutorial_dir: Path) -> int:
Expand Down Expand Up @@ -45,7 +45,7 @@ def generate_tutorial_structure_md(root: Path) -> str:

```text
tutorials/<tutorial-name>/
index.md
README.md
01-*.md
02-*.md
...
Expand Down Expand Up @@ -148,7 +148,7 @@ def generate_content_gaps_md(root: Path) -> str:

A tutorial track is considered production-ready when:

- it has `index.md` with valid local links
- it has `README.md` with valid local links
- it has a coherent numbered chapter sequence
- its summary and snapshot language are not stale or placeholder quality
- it passes repository docs health checks
Expand Down
4 changes: 2 additions & 2 deletions scripts/update_tutorials_readme_snapshot.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

def compute_metrics(root: Path) -> dict:
tutorials_root = root / "tutorials"
tutorial_dirs = sorted([p for p in tutorials_root.iterdir() if p.is_dir() and (p / "index.md").is_file()])
tutorial_dirs = sorted([p for p in tutorials_root.iterdir() if p.is_dir() and (p / "README.md").is_file()])

md_files = [f for d in tutorial_dirs for f in d.glob("*.md")]
md_lines = 0
Expand Down Expand Up @@ -63,7 +63,7 @@ def update_readme_content(content: str, metrics: dict) -> str:
r"\| Tutorial directories \| .* \|": f"| Tutorial directories | {metrics['tutorial_directories']} |",
r"\| Tutorial markdown files \| .* \|": f"| Tutorial markdown files | {metrics['tutorial_markdown_files']} |",
r"\| Tutorial markdown lines \| .* \|": f"| Tutorial markdown lines | {metrics['tutorial_markdown_lines']:,} |",
r"\| Root chapter files \| .* \|": f"| Root chapter files | {metrics['structure_counts']['root_only']} | `index.md` + top-level `01-...md` to `08-...md` |",
r"\| Root chapter files \| .* \|": f"| Root chapter files | {metrics['structure_counts']['root_only']} | `README.md` + top-level `01-...md` to `08-...md` |",
r"\| `docs/` chapter files \| .* \|": f"| `docs/` chapter files | {metrics['structure_counts']['docs_only']} | Deprecated and fully migrated |",
r"\| Index-only roadmap \| .* \|": f"| Index-only roadmap | {metrics['structure_counts']['index_only']} | All catalog entries publish full chapter sets |",
r"\| Mixed root \+ `docs/` \| .* \|": f"| Mixed root + `docs/` | {metrics['structure_counts']['mixed']} | Legacy hybrid layout removed |",
Expand Down
4 changes: 2 additions & 2 deletions scripts/verify_tutorial_sources.py
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ def collect_tutorial_records(root: Path) -> list[TutorialSourceRecord]:
records: list[TutorialSourceRecord] = []

for tutorial_dir in sorted(p for p in tutorials_root.iterdir() if p.is_dir()):
index_path = tutorial_dir / "index.md"
index_path = tutorial_dir / "README.md"
if not index_path.is_file():
continue
text = index_path.read_text(encoding="utf-8", errors="ignore")
Expand Down Expand Up @@ -248,7 +248,7 @@ def render_markdown(report: dict[str, Any]) -> str:
lines = [
"# Tutorial Source Verification Report",
"",
"Automated verification of GitHub source repositories referenced by `tutorials/*/index.md`.",
"Automated verification of GitHub source repositories referenced by `tutorials/*/README.md`.",
"",
f"- generated_on: **{report['generated_on']}**",
f"- tutorials scanned: **{summary['tutorial_count']}**",
Expand Down
8 changes: 4 additions & 4 deletions tutorials/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,8 @@ Use this guide to navigate all tutorial tracks, understand structure rules, and
| Metric | Value |
|:-------|:------|
| Tutorial directories | 191 |
| Tutorial markdown files | 1732 |
| Tutorial markdown lines | 1,048,772 |
| Tutorial markdown files | 1722 |
| Tutorial markdown lines | 1,048,086 |

## Source Verification Snapshot

Expand All @@ -37,7 +37,7 @@ Repository-source verification run against tutorial index references (GitHub API

| Pattern | Count | Description |
|:--------|:------|:------------|
| Root chapter files | 191 | `index.md` + top-level `01-...md` to `08-...md` |
| Root chapter files | 191 | `README.md` + top-level `01-...md` to `08-...md` |
| `docs/` chapter files | 0 | Deprecated and fully migrated |
| Index-only roadmap | 0 | All catalog entries publish full chapter sets |
| Mixed root + `docs/` | 0 | Legacy hybrid layout removed |
Expand All @@ -55,7 +55,7 @@ Each tutorial index should provide:

Each tutorial directory should contain:

- `index.md`
- `README.md`
- `01-...md` through `08-...md` at the tutorial root (not under `docs/`)

## Maintainer Commands
Expand Down
2 changes: 1 addition & 1 deletion tutorials/activepieces-tutorial/01-getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -636,7 +636,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Next Chapter: Chapter 2: System Architecture: App, Worker, Engine](02-system-architecture-app-worker-engine.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
Original file line number Diff line number Diff line change
Expand Up @@ -640,7 +640,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 1: Getting Started](01-getting-started.md)
- [Next Chapter: Chapter 3: Flow Design, Versioning, and Debugging](03-flow-design-versioning-and-debugging.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -638,7 +638,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 2: System Architecture: App, Worker, Engine](02-system-architecture-app-worker-engine.md)
- [Next Chapter: Chapter 4: Piece Development Framework](04-piece-development-framework.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -638,7 +638,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 3: Flow Design, Versioning, and Debugging](03-flow-design-versioning-and-debugging.md)
- [Next Chapter: Chapter 5: Installation and Environment Configuration](05-installation-and-environment-configuration.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -637,7 +637,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 4: Piece Development Framework](04-piece-development-framework.md)
- [Next Chapter: Chapter 6: Admin Governance and AI Provider Control](06-admin-governance-and-ai-provider-control.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -635,7 +635,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 5: Installation and Environment Configuration](05-installation-and-environment-configuration.md)
- [Next Chapter: Chapter 7: API Automation and Embedding Patterns](07-api-automation-and-embedding-patterns.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -638,7 +638,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 6: Admin Governance and AI Provider Control](06-admin-governance-and-ai-provider-control.md)
- [Next Chapter: Chapter 8: Production Operations, Security, and Contribution](08-production-operations-security-and-contribution.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -635,7 +635,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 7: API Automation and Embedding Patterns](07-api-automation-and-embedding-patterns.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
2 changes: 1 addition & 1 deletion tutorials/adk-python-tutorial/01-getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -636,7 +636,7 @@ Suggested trace strategy:

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Next Chapter: Chapter 2: Architecture and Runner Lifecycle](02-architecture-and-runner-lifecycle.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
- [A-Z Tutorial Directory](../../discoverability/tutorial-directory.md)
Original file line number Diff line number Diff line change
Expand Up @@ -637,7 +637,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 1: Getting Started](01-getting-started.md)
- [Next Chapter: Chapter 3: Agent Design and Multi-Agent Composition](03-agent-design-and-multi-agent-composition.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -636,7 +636,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 2: Architecture and Runner Lifecycle](02-architecture-and-runner-lifecycle.md)
- [Next Chapter: Chapter 4: Tools, MCP, and Confirmation Flows](04-tools-mcp-and-confirmation-flows.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -634,7 +634,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 3: Agent Design and Multi-Agent Composition](03-agent-design-and-multi-agent-composition.md)
- [Next Chapter: Chapter 5: Sessions, Memory, and Context Management](05-sessions-memory-and-context-management.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -630,7 +630,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 4: Tools, MCP, and Confirmation Flows](04-tools-mcp-and-confirmation-flows.md)
- [Next Chapter: Chapter 6: Evaluation, Debugging, and Quality Gates](06-evaluation-debugging-and-quality-gates.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -630,7 +630,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 5: Sessions, Memory, and Context Management](05-sessions-memory-and-context-management.md)
- [Next Chapter: Chapter 7: Deployment and Production Operations](07-deployment-and-production-operations.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -636,7 +636,7 @@ Use the following upstream sources to verify implementation details while readin

## Chapter Connections

- [Tutorial Index](index.md)
- [Tutorial Index](README.md)
- [Previous Chapter: Chapter 6: Evaluation, Debugging, and Quality Gates](06-evaluation-debugging-and-quality-gates.md)
- [Next Chapter: Chapter 8: Contribution Workflow and Ecosystem Strategy](08-contribution-workflow-and-ecosystem-strategy.md)
- [Main Catalog](../../README.md#-tutorial-catalog)
Expand Down
Loading