docs: restructure repository guidance

Author: 0xPlayerOne

README.md

@@ -0,0 +1,29 @@
+# Caching and remote caching
+
+## Local workflow caching
+
+The standard runtime uses lockfile- and configuration-keyed caches for package
+stores, Cargo, pip/uv, browser binaries, and applicable build artifacts. Cache
+misses always fall back to a clean locked install. Do not cache credentials,
+generated secrets, or mutable environments without an exact dependency key.
+
+Repositories should measure before enabling large installed-tree or build
+caches. Set repository variables such as `REPO_FOUNDRY_CACHE_PACKAGES` and
+`REPO_FOUNDRY_CACHE_BUILD` only when a repeatable warm-cache benefit is proven.
+
+## Turborepo and Vercel Remote Caching
+
+Turborepo repositories can opt into Vercel Remote Caching with:
+
+- Secret: `TURBO_TOKEN`
+- Repository variable: `TURBO_TEAM`
+
+Non-Turborepo repositories do not need either setting. Deployment to Vercel is
+not required. Custom workflows can pass these values to Turbo directly when
+the repository's task graph benefits from remote reuse.
+
+## Runner selection
+
+Lightweight detection, orchestration, audits, and release metadata jobs can use
+`ubuntu-slim`. Toolchain-heavy builds, native compilation, browsers, and active
+CodeQL analysis should use `ubuntu-latest` unless measurements show otherwise.

docs/CACHING.md

@@ -0,0 +1,56 @@
+# Initialization and synchronization
+
+## Commands
+
+Run the package from a repository root:
+
+```bash
+npx code-foundry init [options]
+npx code-foundry sync [options]
+npx code-foundry doctor
+```
+
+Use `--dry-run` to preview changes. Use `--no-bootstrap` when the repository is
+being initialized in CI or on a machine without mise. Run
+`bash .github/scripts/bootstrap.sh` later to install tools, enable hooks, and
+run the repository doctor.
+
+## Profiles and features
+
+Supported languages are `typescript`, `rust`, `python`, and `solidity`.
+`--languages auto` detects them from manifests and source files. Profiles are
+`auto`, `application`, `monorepo`, and `minimal`.
+
+Standard features are `ci`, `codeql`, `security`, `test`, `draft-pr`,
+`release-pr`, `release`, and `dependabot`. `all` enables every standard
+feature. `--prune` removes disabled standard workflows only; it never removes
+custom workflows.
+
+## Runtime selection
+
+Reusable workflow callers require a literal repository and ref. By default,
+the initializer derives the runtime repository from the source template. Use
+these options for a fork or a staged runtime:
+
+```bash
+npx code-foundry init \
+  --runtime-repository OWNER/REPO \
+  --runtime-ref v1.2.3
+```
+
+Both values are persisted in `.github/template.yml` and rendered into the
+standard callers. `REPO_FOUNDRY_RUNTIME_REPOSITORY` and
+`REPO_FOUNDRY_RUNTIME_REF` provide equivalent environment/repository-variable
+overrides.
+
+## Safety rules
+
+Synchronization preserves authored README and policy documents, existing
+`.mise.toml` selections, application code, custom workflows, and repository
+documentation. Existing licenses are preserved unless a license or license
+file is explicitly selected. Use `--force` only when intentionally refreshing
+protected standard documents.
+
+The initializer generates `.github/template.yml` as the repository-owned
+configuration contract. Keep project-specific settings there rather than
+editing generated workflow callers by hand.

docs/INITIALIZATION.md

@@ -0,0 +1,45 @@
+# Publishing packages
+
+## npm
+
+Set `npm_publish: true` only when the repository owns an npm package. Configure
+npm trusted publishing for the repository's `release.yml` workflow whenever
+possible. An `NPM_TOKEN` secret is the fallback for registries or repositories
+that cannot use trusted publishing.
+
+The package should define its intended visibility explicitly:
+
+```json
+{
+  "publishConfig": {
+    "access": "public"
+  }
+}
+```
+
+Publication occurs only from a Release Please tag; ordinary pushes do not
+publish. The release workflow fails clearly when npm publication is enabled but
+neither trusted publishing nor a token is configured.
+
+## GitHub Releases and GitHub Packages
+
+A GitHub Release is release metadata attached to a Git tag. It is independent
+of the npm registry and of GitHub Packages.
+
+Publishing to npm does not populate the repository's GitHub Packages section.
+If a repository also needs a GitHub Container Registry or npm-compatible
+GitHub Package, add a repository-owned publishing workflow and credentials;
+that is an optional extension rather than part of the universal baseline.
+
+## Provenance and verification
+
+Prefer trusted publishing because it provides short-lived credentials and
+provenance. After a release, verify:
+
+```bash
+npm view PACKAGE_NAME version dist-tags
+gh release view vVERSION
+```
+
+For private or non-npm repositories, leave `npm_publish: false` and retain the
+GitHub Release portion of the standard flow if versioned releases are useful.

docs/PUBLISHING.md

@@ -0,0 +1,20 @@
+# Documentation
+
+These guides describe the reusable repository baseline in provider-neutral
+terms. They are suitable for copying into another repository and adapting with
+its own names, environments, and deployment details.
+
+## Guides
+
+- [Initialization and synchronization](INITIALIZATION.md)
+- [Workflow and CI conventions](WORKFLOWS.md)
+- [Release management](RELEASES.md)
+- [Publishing packages](PUBLISHING.md)
+- [Caching and remote caching](CACHING.md)
+
+## Repository-specific documentation
+
+Add project-specific guides, architecture notes, runbooks, and deployment
+instructions to this directory. The Code Foundry initializer preserves `docs/`
+files during synchronization. Prefer clear, task-oriented filenames and link
+new documents from this index when they become part of the supported workflow.

docs/README.md

@@ -0,0 +1,47 @@
+# Release management
+
+## Branch flow
+
+The standard environment flow is:
+
+```text
+topic branch -> staging -> main -> versioned release
+```
+
+Keep commits Conventional Commit-shaped (`feat:`, `fix:`, `docs:`, `ci:`,
+`chore:`, and so on). Release Please uses them to select patch/minor/major
+versions and generate grouped changelog notes.
+
+The release workflow opens or updates a versioned PR after changes reach
+`main`. Merging that PR updates the changelog, creates the Git tag and GitHub
+Release, and triggers any configured package publication.
+
+For an explicit version, put `Release-As: 2.0.0` in a commit or pull request
+body. Existing `CHANGELOG.md` history remains repository-owned.
+
+## Configuration
+
+Set these values in `.github/template.yml`:
+
+```yaml
+release_type: auto   # auto, node, python, rust, simple, or none
+npm_publish: false   # true only for an npm package
+```
+
+`auto` selects a supported manifest. Use `simple` with `version.txt` for a
+repository without a package manifest and `none` for a repository that should
+not release automatically.
+
+## Pull request permissions
+
+If the default `GITHUB_TOKEN` cannot create pull requests, configure a narrowly
+scoped `RELEASE_PLEASE_TOKEN` repository or organization secret. The release
+workflow needs `contents`, `issues`, and `pull-requests` permissions.
+
+## Operational checklist
+
+1. Merge tested changes from `staging` into `main`.
+2. Review the generated Release Please PR and changelog.
+3. Merge the release PR with the repository's normal linear-history policy.
+4. Confirm the GitHub Release and any package publication.
+5. Synchronize `staging` with the new `main` release commit.

docs/RELEASES.md

@@ -0,0 +1,66 @@
+# Workflow and CI conventions
+
+## Standard triggers
+
+The default standard callers use:
+
+```yaml
+push:
+  branches: [main, staging]
+pull_request:
+  branches: [staging]
+```
+
+Draft PR automation may additionally listen to supported topic branches.
+Custom deployment, indexing, search, Slither, or other workflows are
+repository-owned extensions and should keep their own triggers and permissions.
+
+## Standard workflow responsibilities
+
+| Workflow | Responsibility |
+| --- | --- |
+| CI | Format, lint, type-check, and build |
+| Test | Unit, integration, E2E, and smoke tests |
+| Security | Profile, audits, and public-only Dependency Review |
+| CodeQL | GitHub-native code scanning, kept separate from CI |
+| Draft PR | Create/update development pull requests |
+| Release PR | Promote `staging` into `main` |
+| Release | Release Please, GitHub release, and optional npm publication |
+
+Use concise job names such as `CI / Format`, `Test / Unit`, and
+`CodeQL / Analyze (Python)`. Required checks should match the jobs actually
+enabled for the repository profile.
+
+## Language defaults
+
+- TypeScript/JavaScript: ESLint, Prettier, and Bun's native `bun test`.
+- Rust: default `rustfmt`, Clippy with `-D warnings`, and Cargo tests.
+- Python: Ruff formatting/linting, uv when a compatible lockfile exists, and
+  native Python tests.
+- Solidity: preserve the repository's native Hardhat, Foundry, or specialized
+  test/security workflows.
+
+Jobs detect applicability before installing tools. Empty language or test
+surfaces remain successful and visible, so branch protection does not become
+ambiguous for mixed-language repositories.
+
+## Security behavior
+
+CodeQL is a separate workflow using GitHub's official actions. Dependency
+Review is skipped where GitHub does not support it, while JavaScript, Python,
+and Rust audits remain available without Advanced Security. If GitHub default
+setup is enabled, disable its generated CodeQL workflow to avoid duplicate
+analysis.
+
+## Branch protection
+
+Use the initializer's protection helper after reviewing the repository's
+enabled features:
+
+```bash
+bash .github/scripts/init-repo.sh --protection
+```
+
+Keep strict status checks, linear history, and conversation resolution enabled.
+For a repository with optional features disabled, do not require checks that
+will never run.

docs/WORKFLOWS.md

@@ -18,6 +18,7 @@
   },
   "files": [
     "src",
+    "docs",
     ".github",
     ".githooks",
     ".editorconfig",