Docs

docs: restructure README and add subdirectory guides (#212) #12

	name: Docs

	on:
	pull_request:
	paths:
	- "*/.md"
	- ".github/ISSUE_TEMPLATE/**"
	- ".github/PULL_REQUEST_TEMPLATE.md"
	- ".github/workflows/docs.yml"
	push:
	branches: [main]
	paths:
	- "*/.md"
	- ".github/ISSUE_TEMPLATE/**"
	- ".github/PULL_REQUEST_TEMPLATE.md"
	- ".github/workflows/docs.yml"

	permissions:
	contents: read

	jobs:
	links:
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v4

	- name: Validate active relative Markdown links
	run: \|
	python3 - <<'PY'
	from pathlib import Path
	import re
	import sys

	files = [
	Path("README.md"),
	Path("AGENTS.md"),
	Path(".github/CONTRIBUTING.md"),
	Path(".github/CODE_OF_CONDUCT.md"),
	Path(".github/SECURITY.md"),
	]

	missing = []
	for path in files:
	if not path.exists():
	continue
	text = path.read_text()
	active = re.sub(r"<!--.*?-->", "", text, flags=re.S)
	for raw in re.findall(r"\[[^\]]*\]\(([^)]+)\)", active):
	link = raw.split("#", 1)[0]
	if not link or link.startswith(("http://", "https://", "mailto:")):
	continue
	target = (path.parent / link).resolve()
	try:
	target.relative_to(Path.cwd().resolve())
	except ValueError:
	missing.append((path, raw, "outside repository"))
	continue
	if not target.exists():
	missing.append((path, raw, "missing"))

	if missing:
	for path, raw, reason in missing:
	print(f"{path}: {raw} -> {reason}")
	sys.exit(1)

	print("Active relative Markdown links resolve.")
	PY

	- name: Validate issue template YAML
	run: \|
	ruby -e 'require "yaml"; Dir[".github/ISSUE_TEMPLATE/*.yml"].sort.each { \|p\| YAML.load_file(p); puts "YAML ok: #{p}" }'

Provide feedback