docs: 개발자용 GitHub Pages 포털과 자동 게시 구축

.github/pull_request_template.md

@@ -0,0 +1,22 @@
+## 변경 내용
+
+변경 목적과 독자가 얻는 결과를 간단히 적어 주세요.
+
+## 공개 문서 체크리스트
+
+- [ ] 사례·가이드·실습·리서치 중 올바른 문서 유형과 폴더를 선택했습니다.
+- [ ] 필수 front matter와 `docs-taxonomy.yml`의 분류 값을 사용했습니다.
+- [ ] Microsoft/Azure 기술 주장을 Microsoft Learn MCP와 `verify-with-microsoft-learn` skill로 원문까지 확인했습니다.
+- [ ] 실제 구독·테넌트 ID, 비밀, 내부 URL·IP·호스트명 등 공개 안전성 문제를 제거했습니다.
+- [ ] 필요한 경우 현재 가이드와 시점 고정 사례를 분리하고 서로 연결했습니다.
+- [ ] 아래 로컬 검증을 통과했습니다.
+
+```powershell
+python -m pytest tests/docs -q
+python scripts/docs/validate_metadata.py
+python scripts/docs/validate_sources.py
+python scripts/docs/validate_links.py
+python scripts/docs/validate_public_safety.py
+mkdocs build --strict
+python scripts/docs/validate_search_index.py
+```

.github/skills/verify-with-microsoft-learn/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: verify-with-microsoft-learn
+description: Use when creating, revising, or reviewing public technical documentation that contains Microsoft or Azure product claims.
+---
+
+# Verify with Microsoft Learn
+
+## Core rule
+
+Verify product behavior, support status, limits, versions, configuration steps, and CLI or API usage against current official text. A source URL alone is not evidence of a completed review.
+
+## Workflow
+
+1. Extract every checkable claim from the changed document. Separate product claims from incident-specific observations.
+2. Confirm the `microsoft.docs.mcp` server is connected. Inspect its current tool descriptions through `tools/list`; tool names, parameters, and response shapes can change.
+3. Search Microsoft Learn for each claim using the official product name, feature, version, error, or command. Use the discovered documentation search tool rather than general web search.
+4. Fetch every selected article in full with the discovered article-fetch tool. Search snippets are only candidates.
+5. Compare each claim with the fetched article's scope, prerequisites, supported versions, limitations, and current terminology.
+6. Correct unsupported claims. For a historical case, preserve the observation but state its date and contrast it with current documented behavior.
+7. For Kubernetes or CNCF behavior that Microsoft Learn does not define, also check the relevant `kubernetes.io` or `cncf.io` source. Microsoft Learn remains mandatory for this repository's Azure context.
+8. Record the exact article title and canonical URL in `official_sources`, set `sources_checked_at` to the actual review date, and set `verification_status: verified` only after every material claim is covered.
+9. Run `python scripts/docs/validate_metadata.py`, `python scripts/docs/validate_sources.py`, and `python scripts/docs/validate_links.py`.
+
+If the server is unavailable, no relevant full article can be fetched, or a material conflict remains, set `verification_status: needs-review` and report the unresolved claim. Never use `last_verified` to imply a check that did not occur.
+
+## Evidence contract
+
+```yaml
+verification_status: verified
+sources_checked_at: 2026-09-12
+official_sources:
+  - title: Azure Kubernetes Service documentation
+    url: https://learn.microsoft.com/azure/aks/
+```
+
+Use at least one claim-relevant `https://learn.microsoft.com/` article. Add upstream official sources when they hold the authoritative implementation detail.
+
+## Quick reference
+
+| Claim | Verify |
+|---|---|
+| Supported feature or version | Availability, region, tier, preview/GA status |
+| Configuration procedure | Prerequisites, command syntax, defaults, permissions |
+| Limit or performance statement | Units, scope, exceptions, last-updated context |
+| Historical incident | Observation date separately from current product behavior |
+
+## Common mistakes
+
+- Treating a search snippet as the full source
+- Citing a product landing page that does not support the claim
+- Using blogs, Q&A, or copied examples when an official article exists
+- Marking a document verified while one material claim is unresolved

.github/skills/verify-with-microsoft-learn/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Verify with Microsoft Learn"
+  short_description: "Verify technical docs against Microsoft Learn"
+  default_prompt: "Use $verify-with-microsoft-learn to verify this technical documentation against current official sources."

.github/workflows/docs-ci.yml

@@ -0,0 +1,42 @@
+name: Documentation CI
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install documentation dependencies
+        run: python -m pip install -r requirements-docs.txt
+
+      - name: Run documentation contract tests
+        run: python -m pytest tests/docs -q
+
+      - name: Validate public documentation
+        run: |
+          python scripts/docs/validate_metadata.py
+          python scripts/docs/validate_sources.py
+          python scripts/docs/validate_links.py
+          python scripts/docs/validate_public_safety.py
+
+      - name: Build site strictly
+        run: mkdocs build --strict
+
+      - name: Validate search index
+        run: python scripts/docs/validate_search_index.py

.github/workflows/oryx-python-build-test.yml

@@ -3,7 +3,7 @@ name: Oryx Python 3.11 Build Test
 on:
   push:
     paths:
-      - 'oryx-test/**'
+      - 'samples/azure-app-service/oryx-test/**'
       - '.github/workflows/oryx-python-build-test.yml'
   workflow_dispatch:
 
@@ -20,7 +20,7 @@ jobs:
       - name: Oryx build Python 3.11
         run: |
           docker run --rm \
-            -v ${{ github.workspace }}/oryx-test:/app \
+            -v ${{ github.workspace }}/samples/azure-app-service/oryx-test:/app \
             mcr.microsoft.com/oryx/build:github-actions-debian-bullseye \
             oryx build /app \
               --platform python \
@@ -29,4 +29,4 @@ jobs:
       - name: Verify build output
         run: |
           echo "=== Build output ==="
-          ls -la ./oryx-test/
+          ls -la ./samples/azure-app-service/oryx-test/

.github/workflows/pages.yml

@@ -0,0 +1,71 @@
+name: Deploy documentation to Pages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    permissions:
+      contents: read
+      pages: read
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install documentation dependencies
+        run: python -m pip install -r requirements-docs.txt
+
+      - name: Validate public documentation
+        run: |
+          python scripts/docs/validate_metadata.py
+          python scripts/docs/validate_sources.py
+          python scripts/docs/validate_links.py
+          python scripts/docs/validate_public_safety.py
+
+      - name: Build site strictly
+        run: mkdocs build --strict
+
+      - name: Validate search index
+        run: python scripts/docs/validate_search_index.py
+
+      - name: Configure Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,11 +1,15 @@
 node_modules/
 .env
-.github/skills/
+.github/skills/*
+!.github/skills/verify-with-microsoft-learn/
+!.github/skills/verify-with-microsoft-learn/**
 .venv
 sim-env.json.vscode/
 .mirrord/
 __pycache__/
 *.py[cod]
+.pytest_cache/
+site/
 .worktrees/
 .superpowers/
 monitor/sre-agent-event-lab/evidence/

.vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "microsoft-learn": {
+      "type": "http",
+      "url": "https://learn.microsoft.com/api/mcp"
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1,66 @@
+# Repository instructions
+
+## Public documentation contract
+
+- 상세 기준은 `docs/contributing/index.md`를 단일 설명 문서로 사용한다.
+- 공개 기술 문서는 `docs/<collection>/<service>/<topic>/index.md` page bundle로 작성한다.
+- `<collection>`은 `cases`, `guides`, `labs`, `research` 중 하나이며 front matter의 `document_type`과 일치해야 한다.
+- Azure 제품의 `<service>`는 `azure-`와 공식 전체 제품명을 kebab-case로 조합한다(예: `azure-kubernetes-service`).
+- Microsoft 제품은 공식 명칭을 보존하여 이름이 `Microsoft`로 시작하면 `microsoft-` slug를 사용하고, 오픈소스와 그 밖의 제품은 공식 프로젝트·제품명을 kebab-case로 사용한다.
+- 새 서비스, 기술 또는 태그가 필요할 때만 `docs-taxonomy.yml`을 함께 수정한다.
+- 개별 문서를 추가하기 위해 `mkdocs.yml`, `docs/.nav.yml`, README 또는 수동 문서 목록을 수정하지 않는다. 빌드가 폴더와 메타데이터에서 메뉴·색인을 생성한다.
+
+## Publishing automation
+
+- 문서의 원본은 Markdown page bundle과 front matter다. 기존 분류의 새 글은 `docs/guides/azure-kubernetes-service/<topic>/index.md` 같은 bundle만 추가하고, 메뉴에 문서 경로를 수동 등록하지 않는다.
+- 메뉴 트리, 문서 유형별·서비스별 목록, 태그와 검색 인덱스는 빌드 시 자동 생성한다. 브라우저에서 Markdown을 다시 읽거나 별도의 수동 문서 목록을 동기화하는 구조를 추가하지 않는다.
+- `mkdocs.yml`과 `docs/.nav.yml`은 사이트 공통 설정과 대메뉴 구성에만 사용한다. 새 서비스·기술·태그를 처음 도입할 때의 공통 분류 등록은 `docs-taxonomy.yml`에서 처리한다.
+- 홈의 대표 글은 문서의 `featured: true`로 지정한다. 생성기에 특정 문서 경로나 제목 목록을 하드코딩하지 않는다.
+- 게시 자동화를 바꿀 때는 Markdown bundle 하나를 추가하는 것만으로 메뉴·목록·검색이 갱신되는지 검증한다. 설정 파일의 문자열이 존재하는지만 검사하는 테스트로 대체하지 않는다.
+
+## Reader interface
+
+- 독자는 개발자다. 제목과 설명은 구체적인 증상, 기술적 선택, 관측과 판단의 근거를 드러내고 일반적인 홍보 문구나 관료적인 표현을 피한다.
+- 메뉴는 대메뉴(문서 유형) → 중메뉴(서비스) → 소메뉴(문서)로 구분한다. 문서 이름은 front matter의 `title`, 서비스 이름은 taxonomy를 사용하고 bundle 폴더를 불필요한 추가 단계로 노출하지 않는다.
+- 그룹은 접기·펼치기가 가능하고 현재 문서의 경로만 기본으로 열린다. `navigation.sections`나 `navigation.expand`로 모든 그룹을 강제로 펼치지 않는다.
+- 큰 화면에서는 전체 문서 사이드바를, 작은 화면에서는 햄버거 메뉴를 제공한다. 들여쓰기·굵기·구분선으로 계층을 표시하고 현재 문서를 강조한다.
+- 글자 크기는 GitHub Markdown 수준을 기준으로 한다: 본문 16px, H1 32px, H2 24px, H3 20px, 코드 약 13.6px. 홈 제목만 과도하게 키우지 않으며 밝은·어두운 테마와 모바일에서도 실제 크기·가독성을 확인한다.
+- 검토 상태와 확인일은 사실대로 메타데이터에 유지하되, 마이그레이션·검토 미완료 같은 관리용 안내를 본문 배너나 목록 배지로 자동 노출하지 않는다. 출처 링크와 실제 기술적 제약·비용 경고는 보존한다.
+
+## Content lifecycle
+
+- 발생 시점의 환경, 관측값, 조사와 해결 이력은 `cases`에 보존한다.
+- 현재 권장 절차, 지원 상태와 버전별 차이는 `guides`에서 계속 갱신한다.
+- 한 문서에 두 성격이 섞이면 사례와 가이드로 분리하고 `related_cases`·`related_guides`로 연결한다.
+- 실행 가능한 프로젝트, 배포 매니페스트와 대용량 결과물은 `samples/`에 두고 문서에서는 GitHub 소스 링크를 사용한다.
+- 페이지에서 렌더링할 이미지만 같은 bundle의 `images/`에 두며 의미 있는 대체 텍스트를 작성한다.
+
+## Official-source verification
+
+- Microsoft 또는 Azure의 동작, 지원 여부, 제한, 버전, 구성 단계, CLI/API 사용법을 추가하거나 바꿀 때 `.github/skills/verify-with-microsoft-learn/SKILL.md`의 `verify-with-microsoft-learn` skill을 반드시 사용한다.
+- Microsoft Learn MCP 검색 뒤 선택한 원문 전체를 조회하고, 주장과 적용 범위를 비교한다.
+- `official_sources`, `sources_checked_at`, `verification_status`는 실제 검증 결과와 일치시킨다. URL만 추가한 것은 검증이 아니다.
+- Microsoft Learn이 최종 권위가 아닌 Kubernetes·CNCF 세부 동작은 upstream 공식 문서도 함께 확인한다.
+- 의미 검증을 완료하지 못하면 `verification_status: needs-review`로 남기고 완료했다고 표현하지 않는다.
+
+## Public safety
+
+- 고객·조직·사용자 실명, 구독·테넌트 ID, 비밀, 연결 문자열, 내부 URL·IP·호스트명, 개인정보가 담긴 로그와 승인되지 않은 화면을 공개 문서에 넣지 않는다.
+- 실제 식별자는 문서 전체에서 일관된 가상 값으로 치환한다.
+
+## Required validation
+
+문서 CI는 `tests/docs`와 공개 문서·사이트 검증을 대상으로 한다. SRE 실습 등 `samples/`의 애플리케이션 테스트나 의존성을 문서 CI에 묶지 않는다. 게시 스크립트나 사이트 동작을 변경하면 `python -m pytest tests/docs -q`도 실행한다.
+
+문서 또는 사이트 구성을 변경한 뒤 저장소 루트에서 실행한다.
+
+```powershell
+python scripts/docs/validate_metadata.py
+python scripts/docs/validate_sources.py
+python scripts/docs/validate_links.py
+python scripts/docs/validate_public_safety.py
+mkdocs build --strict
+python scripts/docs/validate_search_index.py
+```
+
+테스트나 검증 실패를 무시하거나 생성된 `site/` 및 검색 인덱스를 커밋하지 않는다.

CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# 기여하기
+
+새 공개 문서는 `docs/<collection>/<service>/<topic>/index.md`에 추가합니다. 올바른 폴더와 front matter를 사용하면 메뉴와 색인은 빌드 시 자동 생성됩니다.
+
+문서 유형 선택, 메타데이터, 본문 구조, 태그, 이미지와 공개 안전성의 기준 문서는 [상세 기여 지침](docs/contributing/index.md)입니다.
+
+Microsoft 또는 Azure 기술 내용을 새로 쓰거나 바꿀 때는 repository skill `verify-with-microsoft-learn`을 사용해 Microsoft Learn 원문과 대조하고 출처 메타데이터를 갱신해야 합니다.
+
+제출 전 다음을 실행하세요.
+
+```powershell
+python scripts/docs/validate_metadata.py
+python scripts/docs/validate_sources.py
+python scripts/docs/validate_links.py
+python scripts/docs/validate_public_safety.py
+mkdocs build --strict
+python scripts/docs/validate_search_index.py
+```