Add localized VitePress docs site and Pages deploy

.github/workflows/deploy-docs.yml

@@ -0,0 +1,73 @@
+name: Deploy Docs
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/deploy-docs.yml"
+      - "docs/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/deploy-docs.yml"
+      - "docs/**"
+      - "package.json"
+      - "pnpm-lock.yaml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.12.4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        run: pnpm docs:build
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -4,3 +4,5 @@ coverage
 .DS_Store
 .pnpm-store
 *.tsbuildinfo
+docs/.vitepress/cache
+docs/.vitepress/dist

README.md

@@ -4,6 +4,26 @@
 
 It keeps the real configuration sources and the applying CLI together so that new and existing repositories can adopt the same baseline with a small, reviewable diff.
 
+## Documentation
+
+Structured docs live in `docs/` and are intended to make reviews and spec discussions easier.
+
+The VitePress docs support both English and Japanese.
+Docs are intended to deploy to GitHub Pages from `main` via GitHub Actions.
+
+- overview: `docs/index.md`
+- concepts and file strategies: `docs/concepts.md`
+- CLI behavior: `docs/cli.md`
+- base preset details: `docs/templates/base.md`
+- roadmap and deferred work: `docs/roadmap.md`
+- Japanese pages: `docs/ja/`
+
+To run the docs locally:
+
+```sh
+pnpm docs:dev
+```
+
 ## What This Repository Does
 
 This repository is designed around three responsibilities:

docs/.vitepress/config.mts

@@ -0,0 +1,92 @@
+import { defineConfig } from "vitepress";
+
+const repositoryName = process.env.GITHUB_REPOSITORY?.split("/")[1];
+const base =
+  process.env.GITHUB_ACTIONS && repositoryName ? `/${repositoryName}/` : "/";
+
+const englishNav = [
+  { text: "Overview", link: "/" },
+  { text: "Concepts", link: "/concepts" },
+  { text: "CLI", link: "/cli" },
+  { text: "Base Template", link: "/templates/base" },
+  { text: "Roadmap", link: "/roadmap" },
+];
+
+const englishSidebar = [
+  {
+    text: "Guide",
+    items: [
+      { text: "Overview", link: "/" },
+      { text: "Concepts", link: "/concepts" },
+      { text: "CLI", link: "/cli" },
+      { text: "Base Template", link: "/templates/base" },
+      { text: "Roadmap", link: "/roadmap" },
+    ],
+  },
+];
+
+const japaneseNav = [
+  { text: "概要", link: "/ja/" },
+  { text: "基本概念", link: "/ja/concepts" },
+  { text: "CLI", link: "/ja/cli" },
+  { text: "Base Template", link: "/ja/templates/base" },
+  { text: "ロードマップ", link: "/ja/roadmap" },
+];
+
+const japaneseSidebar = [
+  {
+    text: "ガイド",
+    items: [
+      { text: "概要", link: "/ja/" },
+      { text: "基本概念", link: "/ja/concepts" },
+      { text: "CLI", link: "/ja/cli" },
+      { text: "Base Template", link: "/ja/templates/base" },
+      { text: "ロードマップ", link: "/ja/roadmap" },
+    ],
+  },
+];
+
+export default defineConfig({
+  title: "Project Standards",
+  description: "Shared repository standards, templates, and CLI workflows.",
+  base,
+  lastUpdated: true,
+  themeConfig: {
+    socialLinks: [
+      {
+        icon: "github",
+        link: "https://github.com/Jabelic-Works/project-standards",
+      },
+    ],
+  },
+  locales: {
+    root: {
+      label: "English",
+      lang: "en-US",
+      title: "Project Standards",
+      description: "Shared repository standards, templates, and CLI workflows.",
+      themeConfig: {
+        nav: englishNav,
+        sidebar: englishSidebar,
+        langMenuLabel: "Languages",
+        lastUpdatedText: "Last updated",
+        outlineTitle: "On this page",
+        returnToTopLabel: "Return to top",
+      },
+    },
+    ja: {
+      label: "日本語",
+      lang: "ja-JP",
+      title: "Project Standards",
+      description: "共有リポジトリ標準、テンプレート、CLI ワークフロー。",
+      themeConfig: {
+        nav: japaneseNav,
+        sidebar: japaneseSidebar,
+        langMenuLabel: "言語",
+        lastUpdatedText: "最終更新",
+        outlineTitle: "このページについて",
+        returnToTopLabel: "ページ上部へ戻る",
+      },
+    },
+  },
+});

docs/cli.md

@@ -0,0 +1,65 @@
+# CLI
+
+## Commands
+
+The initial CLI entrypoint supports:
+
+- `init`
+- `apply`
+- `diff`
+- `doctor` as a stub
+- `upgrade` as a stub
+
+## Typical workflow
+
+For an existing repository:
+
+1. Run `diff` first to preview the proposed changes.
+2. Review the plan and decide whether the target repository is ready for the preset.
+3. Run `apply` with `--dry-run` if you want an extra safety check.
+4. Run `apply` for the real write once the diff looks correct.
+
+For a new repository:
+
+1. Run `init` against an empty or intentionally prepared directory.
+2. Review the created baseline files.
+3. Add repository-specific setup on top of the generated scaffold.
+
+## Example usage
+
+Install dependencies and build the workspace:
+
+```sh
+pnpm install
+pnpm build
+```
+
+Show help:
+
+```sh
+node packages/cli/dist/index.js --help
+```
+
+Preview a repository diff:
+
+```sh
+node packages/cli/dist/index.js diff ../target-repository
+```
+
+Apply only quality-related files:
+
+```sh
+node packages/cli/dist/index.js apply ../target-repository --include quality --dry-run
+```
+
+Initialize a new repository directory:
+
+```sh
+node packages/cli/dist/index.js init ../new-repository --yes
+```
+
+## Current limitations
+
+- stack composition is reserved for future preset composition
+- dependency installation in target repositories is not yet automated
+- richer merge behavior for partially managed files is deferred

docs/concepts.md

@@ -0,0 +1,44 @@
+# Concepts
+
+## Design goals
+
+- support both new repositories and existing repositories
+- stay idempotent wherever possible
+- make `diff` and `--dry-run` the default review path
+- avoid clobbering repository-specific files by default
+- keep preset and template expansion easy for future stacks
+
+## Presets
+
+A preset is a named bundle of template files plus metadata.
+
+Today the repository ships a single preset, `base`, defined by `templates/base/preset.json`.
+
+Each entry in the preset maps:
+
+- a source file inside `templates/<preset>/files/`
+- a target file path in the repository being updated
+- a file strategy that decides whether the change is safe to apply
+- optional tags used for partial rollout such as `quality` or `ai`
+
+## File strategies
+
+The current MVP uses two strategies:
+
+- `create_if_missing`: create a file only when it does not already exist
+- `replace_if_managed`: replace a file only when it contains the managed marker
+
+This keeps existing repositories safe while still allowing standards-managed files to be upgraded later.
+
+## Managed marker
+
+Managed files use the marker `managed-by: @jabelic/standards`.
+
+When a file is marked as managed, the planner can replace it on future runs.
+When the marker is absent, the planner treats the file as repository-owned and skips replacement unless forced.
+
+## Shared config packages
+
+Some generated files are thin entrypoints that reference shared packages from this monorepo instead of copying large config blocks into each target repository.
+
+That keeps standards centralized, but it also means some templates currently assume target-repository dependency installation that is still deferred in the MVP.

docs/index.md

@@ -0,0 +1,45 @@
+# Project Standards
+
+`project-standards` is a pnpm monorepo for managing repository standards in one place.
+
+It keeps the real configuration sources and the applying CLI together so that new and existing repositories can adopt the same baseline with a small, reviewable diff.
+
+## What this repository does
+
+This repository combines three responsibilities:
+
+- shared configuration packages for tools that should be referenced instead of copied
+- repository templates for files that must exist inside each target repository
+- a Node.js CLI that can plan, diff, and apply those files safely
+
+The current MVP focuses on a small base preset with:
+
+- Renovate baseline config
+- shared ESLint flat config with Stylistic rules
+- Oxlint and Oxfmt starter files
+- `AGENTS.md`, `CLAUDE.md`, Cursor rules, and Cursor commands
+
+## Read next
+
+- [Concepts](./concepts.md)
+- [CLI](./cli.md)
+- [Base Template](./templates/base.md)
+- [Roadmap](./roadmap.md)
+
+## Workspace layout
+
+```text
+.
+├── docs
+├── packages
+│   ├── cli
+│   ├── core
+│   ├── eslint-config
+│   └── renovate-config
+├── templates
+│   └── base
+├── package.json
+├── pnpm-workspace.yaml
+├── tsconfig.base.json
+└── tsconfig.json
+```