docs: streamline README onboarding and process guides

[mnriem]

Description

Streamline the README so first-time setup stays focused and each process explains its own execution steps.

• Move existing-install/version guidance into the PyPI guide, link it from Upgrade, and retain agent-selection details in Installation.
• Simplify the SDD, bug-fixing, and assessment examples while preserving their steps, outcomes, review guidance, and assessment-to-SDD prerequisites.
• Keep the upstream capability inventory intact and use practical examples in the customization section instead of repeating that inventory. Include integrations and custom workflow steps in the customization guide.
• Replace the old tutorial-video overview with an In the news section linking both GitHub Open Source Friday episodes. Remove stale video links from the English, Chinese, Japanese, and Korean READMEs.

The intended Pages links are preserved. During review, the Catalog page and extension-runtime-events fragment were not yet deployed; the upstream documentation workflow was confirmed pending. Their source files and headings exist.

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest
• Tested with a sample project (if applicable)

Documentation-only changes; the CLI smoke test, pytest suite, sample-project execution, and DocFX build were not run. No executable code, command templates, dependencies, or workflow configuration changed.

• git --no-pager diff --check — passed.
• git diff --cached --check — passed before committing.
• The Python command below — passed: 130 local/documentation links and fragments resolve across the four READMEs; no stale quickstart video links remain.
• Reviewed the command examples against the current guides and templates. Both news videos were verified as GitHub uploads.

Reproduce README source-link validation

python3 - <<'PY'
from pathlib import Path
from urllib.parse import urlsplit, unquote
import re, unicodedata

def anchors(path):
    text = path.read_text()
    result = set(re.findall(r'<a\s+id="([^"]+)"', text))
    for heading in re.findall(r'^#{1,6}\s+(.+)$', text, re.M):
        heading = re.sub(r'\[([^\]]+)\]\([^)]*\)', r'\1', heading)
        heading = re.sub(r'<[^>]+>', '', heading).lower()
        result.add(''.join(c for c in heading if c in ' -_' or unicodedata.category(c)[0] in 'LN').replace(' ', '-'))
    return result

count = 0
for source in map(Path, ('README.md', 'README.ja.md', 'README.zh-CN.md', 'README.ko.md')):
    text = source.read_text()
    assert 'quickstart.html#video-overview' not in text, f'Stale video link in {source}'
    for link in re.findall(r'(?<!!)\[[^\]]+\]\(([^\s)]+)\)', text):
        parts = urlsplit(link)
        if parts.netloc == 'github.github.io' and parts.path.startswith('/spec-kit/'):
            relative = parts.path[len('/spec-kit/'):]
            target = Path('docs') / (relative.removesuffix('.html') + '.md' if relative else 'index.md')
        elif not parts.scheme:
            target = source.parent / unquote(parts.path) if parts.path else source
        else:
            continue
        assert target.is_file(), f'{source}: missing target {link}'
        assert not parts.fragment or unquote(parts.fragment) in anchors(target), f'{source}: missing fragment {link}'
        count += 1
print(f'All {count} local/documentation links and fragments resolve across the four READMEs; no stale video links remain.')
readme = Path('README.md').read_text()
assert 'establish a project constitution if needed' in readme
assert readme.count('## Capabilities') == 1
assert '**' not in readme
print('Assessment handoff, capability inventory, and body emphasis checks passed.')
PY

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Authored by GitHub Copilot using GPT-6.1 Sol (model ID: gpt-6.1-sol), acting for @mnriem. The user directed the scope and iteratively reviewed wording; the agent performed the edits, documentation review, link checks, Git operations, and PR drafting. Agent-authored/autonomous work is disclosed without claiming complete human line-by-line review; the reasoning-effort setting was not exposed. Assistance covered documentation and an ad hoc validation command, not product-code generation.

[Copilot]

🟡 Changes recommended

The PyPI upgrade advice directs pipx/pip users to uv, which can create duplicate CLI installations.

1 open issue

• Scope upgrade instructions to the user's original installation tool · New

What changed in this PR

Streamlines Spec Kit onboarding and moves detailed setup guidance into dedicated documentation.

Changes:

• Simplifies setup and process examples.
• Expands upgrade and customization guidance.
• Replaces the old video overview with news links and removes stale translated links.

AI disclosure: GitHub Copilot for the requester; model/settings unavailable; automated documentation review.

File	Description
README.zh-CN.md	Removes stale video link.
README.md	Simplifies onboarding and adds news links.
README.ko.md	Removes stale video link and anchor.
README.ja.md	Removes stale video link.
docs/​upgrade.md	Links PyPI-specific upgrade instructions.
docs/​quickstart.md	Removes obsolete video section.
docs/​installation.md	Adds agent-selection and invocation guidance.
docs/​install/​pypi.md	Adds installed-version and upgrade advice.
docs/​guides/​customization.md	Covers integrations and custom workflow-step packages.

_{Review effort: Max}

[mnriem]

Updated in 1d17b19: the PyPI guide now scopes uv repeated-install behavior to uv installations and directs users to upgrade with their original installer (uv, pipx, or pip). It also warns that switching installers can create duplicate installations and leave the old executable first on PATH. Checked the wording against the existing per-installer Upgrade section; git --no-pager diff --check passed. No executable behavior changed.

AI disclosure: Posted for @mnriem by GitHub Copilot using GPT-6.1 Sol (gpt-6.1-sol), autonomous documentation editing and review-response generation; reasoning-effort setting not exposed.

[Copilot]

🟢 Approval recommended

The documentation changes introduce no blocking issues; remaining suggestions are non-blocking.

No open issues 🎉

1 resolved since last review

• Scope upgrade instructions to the user's original installation tool

_{Review effort: Max}