[codex] Clarify TypeScript source and generated artifacts

.gitattributes

@@ -0,0 +1,25 @@
+# Keep GitHub language statistics focused on hand-written source.
+# These files are committed for npm package usability, CLI smoke tests, or
+# generated-output drift checks, but contributors should edit src/**/*.ts,
+# templates/**, policy/**, and docs/** instead.
+
+/bin/**/*.js linguist-generated=true
+/bin/**/*.d.ts linguist-generated=true
+/emitter/**/*.js linguist-generated=true
+/emitter/**/*.d.ts linguist-generated=true
+/lib/**/*.js linguist-generated=true
+/lib/**/*.d.ts linguist-generated=true
+/parser/**/*.js linguist-generated=true
+/parser/**/*.d.ts linguist-generated=true
+/validator/**/*.js linguist-generated=true
+/validator/**/*.d.ts linguist-generated=true
+/scripts/**/*.js linguist-generated=true
+/scripts/**/*.d.ts linguist-generated=true
+
+/tests/golden/** linguist-generated=true
+/dist/** linguist-generated=true
+/coverage/** linguist-generated=true
+/examples/**/dist/** linguist-generated=true
+
+# Generated from policy/schema.json by npm run types:gen.
+/src/types/policy.d.ts linguist-generated=true

CONTRIBUTING.ja.md

@@ -14,10 +14,10 @@
 
 ### コード・ドキュメント
 
-1. リポジトリを **Fork** し、`main` からブランチを作成（例: `fix/admin-gate`, `docs/quickstart`）。
+1. リポジトリを **Fork** し、`develop` からブランチを作成（例: `fix/admin-gate`, `docs/quickstart`）。
 2. **変更**は小さく分けたコミットで行ってください。`.ja` が付かないファイルとコード内コメントは **英語**、`.ja` ファイルには **日本語** のみ記載してください。
 3. **手動でテスト**: 変更したランタイム（CloudFront Functions のコンソール、Workers の `wrangler dev` など）で動作確認してください。
-4. **Pull Request** を `main` 向けに作成し、短い説明と、あれば Issue へのリンクを書いてください。
+4. **Pull Request** を `develop` 向けに作成し、短い説明と、あれば Issue へのリンクを書いてください。
 
 ---
 
@@ -41,12 +41,12 @@ PR 作成前に、次のチェックがローカルで通ることを確認し
 6. `npm run test:drift`
 7. `npm run test:security-baseline`
 
-GitHub Actions でも、`main` への push/PR で同じゲートを実行します。
+GitHub Actions でも、`develop` への push/PR で同じゲートを実行します。
 
 リリースはタグで自動化しています:
 
 1. `package.json` の version を更新
-2. `main` へコミット/プッシュ
+2. リリースブランチへコミット/プッシュ
 3. `vX.Y.Z` タグを push
 4. `.github/workflows/release-npm.yml` が品質ゲートを実行し、成功時のみ npm 公開
 
@@ -66,13 +66,31 @@ GitHub Actions でも、`main` への push/PR で同じゲートを実行しま
 
 ## リポジトリ構成
 
+- `src/` - TypeScript ソース。CLI、コンパイラ、ライブラリ、テストのロジックはここを編集します。
+- `bin/`, `lib/`, `scripts/`, `parser/`, `validator/`, `emitter/` - `npm run build:ts` が出力する compiled JavaScript と `.d.ts` の package artifact。直接編集しないでください。
 - `docs/` – アーキテクチャ、脅威モデル、判断マトリクス、クイックスタート（英語 + `.ja`）。
 - `policy/` – YAML ポリシー。`profiles/` にプロファイル（例: `balanced.yml`）を配置。
+- `templates/` - compiler が deploy 可能な edge code を生成するために使う runtime template。
+- `tests/golden/` - 生成された drift fixture。手編集ではなく drift workflow で更新します。
 - `runtimes/` – CloudFront Functions、Lambda@Edge、Cloudflare Workers。コード・コメントは **英語**。
 - `examples/` – AWS CloudFront / Cloudflare のデプロイ例。
 
 ---
 
+## ソースと生成物
+
+正となる実装ソースは `src/**/*.ts`、`templates/` 配下の runtime template、policy/docs です。root 配下の JavaScript は、npm 利用者が TypeScript build なしで package を実行できるようにするため、また checkout 直後の CLI smoke test を成立させるために commit しています。
+
+TypeScript ソースを変更するときは:
+
+1. 対応する `src/` 配下のファイルを編集します。
+2. `npm run build:ts` を実行します。
+3. package surface に含まれる artifact が変わる場合は、`src/**/*.ts` と生成された artifact（`scripts/*.js`, `lib/*.js` など）の両方を commit します。
+
+生成済み JavaScript や `.d.ts` を直接編集しないでください。`.gitattributes` では package artifact、golden fixture、coverage output、生成型定義を generated として扱い、GitHub の言語統計が手書きソースをより正確に表すようにしています。
+
+---
+
 ## コードと言語
 
 - **`.ja` が付かないファイル**（`.js`, `.ts`, `.yml`, `.md` 等）: **英語のみ**（コメント・ドキュメント・PR のコミットメッセージ）。

CONTRIBUTING.md

@@ -14,10 +14,10 @@ Thank you for your interest in contributing. This document explains how to propo
 
 ### Code and documentation
 
-1. **Fork** the repository and create a branch from `main` (e.g. `fix/admin-gate`, `docs/quickstart`).
+1. **Fork** the repository and create a branch from `develop` (e.g. `fix/admin-gate`, `docs/quickstart`).
 2. **Make your changes** in small, focused commits. Use English for all non–`.ja` files and code comments; Japanese only in `.ja` files.
 3. **Test** manually: run the runtime you changed (e.g. CloudFront Functions in console, Workers with `wrangler dev`) and verify behavior.
-4. **Open a Pull Request** against `main` with a short description and, if relevant, link to an issue.
+4. **Open a Pull Request** against `develop` with a short description and, if relevant, link to an issue.
 
 ---
 
@@ -41,12 +41,12 @@ Before opening a PR, ensure these checks pass locally:
 6. `npm run test:drift`
 7. `npm run test:security-baseline`
 
-GitHub Actions runs the same gate on push/PR to `main`.
+GitHub Actions runs the same gate on push/PR to `develop`.
 
 Release is automated by tag:
 
 1. Update `package.json` version.
-2. Push commit to `main`.
+2. Push commit to the release branch.
 3. Push tag `vX.Y.Z`.
 4. `.github/workflows/release-npm.yml` runs the full gate and publishes to npm only when green.
 
@@ -71,13 +71,31 @@ Release is automated by tag:
 
 ## Repository layout
 
+- `src/` - TypeScript source. Edit this for CLI, compiler, library, and test logic.
+- `bin/`, `lib/`, `scripts/`, `parser/`, `validator/`, `emitter/` - Compiled JavaScript and `.d.ts` package artifacts emitted by `npm run build:ts`. Do not edit these directly.
 - `docs/` – Architecture, threat model, decision matrix, quick start (English + `.ja`).
 - `policy/` – YAML policy; `profiles/` holds profile variants (e.g. `balanced.yml`).
+- `templates/` - Runtime templates used by the compiler to generate deployable edge code.
+- `tests/golden/` - Generated drift fixtures. Update via the drift workflow, not by hand.
 - `runtimes/` – CloudFront Functions, Lambda@Edge, Cloudflare Workers. Code and comments in **English**.
 - `examples/` – Deploy examples for AWS CloudFront and Cloudflare.
 
 ---
 
+## Source vs generated artifacts
+
+The authoritative implementation source is `src/**/*.ts`, plus runtime templates under `templates/` and policy/docs files. The root-level JavaScript files are committed so npm consumers can run the package without a TypeScript build step and so CLI smoke tests work from a checkout.
+
+When changing TypeScript source:
+
+1. Edit the matching file under `src/`.
+2. Run `npm run build:ts`.
+3. Commit both the `src/**/*.ts` change and the generated package artifact (`scripts/*.js`, `lib/*.js`, etc.) when the artifact is part of the package surface.
+
+Do not edit generated JavaScript or `.d.ts` files directly. `.gitattributes` marks package artifacts, golden fixtures, coverage output, and generated type files as generated so GitHub language statistics reflect the hand-written source more accurately.
+
+---
+
 ## Code and language
 
 - **Files without `.ja`** (including `.js`, `.ts`, `.yml`, `.md`): **English only** (comments, docs, commit messages in PR).

README.ja.md

@@ -72,16 +72,20 @@
 
 ```
   README.md
+  src/
+    bin/cli.ts             # CLI の TypeScript ソース
+    scripts/               # compiler / test / tool の TypeScript ソース
+    lib/                   # public library API の TypeScript ソース
   bin/
-    cli.js                 # CLI エントリ (npx cdn-security)
+    cli.js                 # compiled package artifact: CLI エントリ (npx cdn-security)
   docs/
     quickstart.md
     policy-runtime-sync.md
   policy/
     security.yml / base.yml
     profiles/
   scripts/
-    compile.js
+    compile.js             # src/scripts/*.ts から compile された artifact
     compile-cloudflare.js
     compile-infra.js
     policy-lint.js
@@ -99,6 +103,8 @@
   examples/
 ```
 
+package code の正となるソースは `src/**/*.ts` です。root 配下の JavaScript と `.d.ts` は `npm run build:ts` が生成する package artifact で、npm 利用者が TypeScript build なしで CLI を実行できるよう commit しています。`templates/` 配下の runtime template は手書きで、deploy 可能な `dist/edge/` 出力を生成するために使われます。
+
 Terraform / CloudFormation / CDK / WAF の利用例は [IaC 連携](docs/iac.ja.md) を参照。
 
 ### 運用ドキュメント

README.md

@@ -71,8 +71,12 @@ This framework addresses these with **"policy-driven" + "runtime separation"**.
 
 ```
   README.md
+  src/
+    bin/cli.ts             # TypeScript source for the CLI
+    scripts/               # TypeScript source for compilers, tests, and tools
+    lib/                   # TypeScript source for public library APIs
   bin/
-    cli.js                 # CLI entry (npx cdn-security)
+    cli.js                 # Compiled package artifact: CLI entry (npx cdn-security)
   docs/
     architecture.md
     quickstart.md
@@ -81,7 +85,7 @@ This framework addresses these with **"policy-driven" + "runtime separation"**.
     security.yml / base.yml
     profiles/
   scripts/
-    compile.js
+    compile.js             # Compiled from src/scripts/*.ts
     compile-cloudflare.js
     compile-infra.js
     policy-lint.js
@@ -99,6 +103,8 @@ This framework addresses these with **"policy-driven" + "runtime separation"**.
   examples/
 ```
 
+The authoritative source for package code lives under `src/**/*.ts`. Root-level JavaScript and `.d.ts` files are committed package artifacts generated by `npm run build:ts` so npm consumers can run the CLI without a TypeScript build step. Runtime templates under `templates/` are hand-written and are used to generate deployable `dist/edge/` output.
+
 See [IaC integration](docs/iac.md) for Terraform / CloudFormation / CDK / WAF usage.
 
 ### Operational docs