Publish docs/ to GitHub Pages with navigable index

Summary

Added an automated docs publishing flow to GitHub Pages and generated a new docs/index.html browsing experience so docs are easy to navigate at /islandflow/docs/.

Changes Made

• Added scripts/generate-docs-index.mjs to build a browsable index of files under docs/.
• Added .github/workflows/docs-pages.yml to publish docs to GitHub Pages on pushes to main.
• Generated docs/index.html from current docs content.
• Configured deployment artifact layout so docs are available at /docs/ under the project Pages site.

Context

The repository already stores operational and implementation documentation under docs/, but there was no dedicated GitHub Pages pipeline and no curated index page for discovery. This task focused on syncing that folder to Pages and making it easy to browse by category and filename.

Important Implementation Details

• The index generator excludes hidden files and avoids self-including docs/index.html.
• Files are grouped by first path segment (turns, general, plans, and others) with quick category chips.
• The index includes client-side filtering so users can search docs by path text in-browser.
• Pages deployment packages a site/ payload where docs are copied into site/docs and root redirects to ./docs/.

Relevant Diff Snippets

Snippets are shown in a compact style aligned with diffs.com presentation patterns.

+++ .github/workflows/docs-pages.yml
name: Publish Docs
on:
  push:
    branches: [main]
    paths:
      - "docs/**"
      - "scripts/generate-docs-index.mjs"
      - ".github/workflows/docs-pages.yml"
  workflow_dispatch:

jobs:
  build:
    steps:
      - uses: actions/checkout@v4
      - uses: actions/configure-pages@v5
      - run: node scripts/generate-docs-index.mjs
      - run: cp -R docs/. site/docs/
      - uses: actions/upload-pages-artifact@v3
  deploy:
    needs: build
    steps:
      - uses: actions/deploy-pages@v4

+++ scripts/generate-docs-index.mjs
const files = await collectDocsFiles(docsDir);
const html = renderDocument(files);
await fs.writeFile(outputFile, html, "utf8");

// Generated index features:
// - grouped sections
// - search filter
// - file size and modified time metadata
// - links preserving docs folder structure

Expected Impact for End-Users

• Docs are reachable via a stable Pages URL path: dirtydishes.github.io/islandflow/docs/.
• Readers can quickly scan categories and search by filename instead of relying on raw directory browsing.
• New docs added to the repository are published automatically on main pushes.

Validation

• Ran node scripts/generate-docs-index.mjs successfully.
• Ran node --check scripts/generate-docs-index.mjs for syntax validation.
• Confirmed generated index contains expected navigation/search markers and category anchors.

Issues, Limitations, and Mitigations

• GitHub Pages must be enabled for this repository and set to GitHub Actions deployment.
• The index reflects files present at build time and does not include full-text search inside documents.
• Markdown files are linked as-is; rendering behavior depends on GitHub Pages static hosting behavior.

Follow-up Work

• Add a docs landing page summary for key collections (turn docs, runbooks, daily notes).
• Optionally add link-checking in CI for docs URLs and local references.
• Consider tagging docs with metadata for richer filtering by date, topic, and type.