docs: state the purpose, goals, and non-goals of the repository and each package

AGENTS.md

@@ -2,7 +2,16 @@
 
 - Name: `willbooster-shared`
 - Package Manager: bun
-- This codebase is yours: how it's built is your call, and you'll keep building on it; what it's for is set by the requester.
+- Purpose: People and AI agents work on any WillBooster repository without learning it first, because every repository follows the same conventions, runs the same commands, and shares the same code.
+- Goals:
+  - An AI agent develops, verifies, and releases in any WillBooster repository without repository-specific guidance from a person.
+  - Every repository stays on the organization's current conventions without anyone configuring it by hand.
+  - The same command does the same job in every repository, whatever its framework or deploy target.
+  - Code that two or more WillBooster projects need exists once.
+- Non-goals:
+  - Supporting repositories outside WillBooster and WillBoosterLab beyond best effort.
+  - Running on Windows.
+- This codebase is yours: how it's built is your call, and you'll keep building on it; what it's for is set by the Project Information above and the requester.
 
 ## General Instructions
 
@@ -39,6 +48,7 @@
 - Put temporary files in `.tmp`; use `/tmp` only for files that must live outside the repo.
 - Before finishing, delete every temporary file, backup, and external resource (e.g., databases, deployed Workers, branches) you created during the task for experiments or verification, without asking, after recording any findings worth keeping in your final response or in a file you keep. Keep an item only when a next step the user requested needs it or it holds the only copy of pre-task data the task was not meant to discard (e.g., a backup a tool kept because restoring it conflicted), and then state in your final response why and the command that deletes it.
 - `AGENTS.md` and `.gemini/styleguide.md` are generated by `wbfy`; edit agent instructions only in `AGENTS_EXTRA.md`, and the following only in the YAML front matter of `README.md`, from what the project's owners have stated, never inferred from the code: `purpose` (text: whose situation the project exists to change, and how), `goals` (list: the conditions under which the purpose is realized, highest priority first), `nonGoals` (list: what is deliberately left out), and `milestones` (list: the checkpoints on the way to the goals, each a capability to ship or a business result to reach that can be decided as reached or not, as a target without its current value, in the order to reach them). Each list holds at most five items. This repository is public: write there only what may be public.
+- Use `Goals` under Project Information to choose between alternatives, an earlier goal outweighing a later one; they never widen what a task requests.
 - Tool versions (e.g., node) are pinned in `mise.toml`; run `mise install` after changing it and never install those tools globally instead.
 - `bunfig.toml` uses Bun's isolated linker, so only declared dependencies resolve. If an import fails to resolve, declare that package in the `package.json` that imports it; never switch `linker` to `hoisted` or add to `publicHoistPattern` to work around it.
 

README.md

@@ -1,3 +1,15 @@
+---
+purpose: People and AI agents work on any WillBooster repository without learning it first, because every repository follows the same conventions, runs the same commands, and shares the same code.
+goals:
+  - An AI agent develops, verifies, and releases in any WillBooster repository without repository-specific guidance from a person.
+  - Every repository stays on the organization's current conventions without anyone configuring it by hand.
+  - The same command does the same job in every repository, whatever its framework or deploy target.
+  - Code that two or more WillBooster projects need exists once.
+nonGoals:
+  - Supporting repositories outside WillBooster and WillBoosterLab beyond best effort.
+  - Running on Windows.
+---
+
 # shared
 
 [![Test](https://github.com/WillBooster/shared/actions/workflows/test.yml/badge.svg)](https://github.com/WillBooster/shared/actions/workflows/test.yml)

packages/shared-lib-blitz-next/README.md

@@ -1 +1,5 @@
+---
+purpose: WillBooster Blitz.js apps share one implementation of common middleware instead of each writing its own.
+---
+
 # @willbooster/shared-lib-blitz-next

packages/shared-lib-next/README.md

@@ -1 +1,5 @@
+---
+purpose: WillBooster Next.js apps share one implementation of common middleware instead of each writing its own.
+---
+
 # @willbooster/shared-lib-next

packages/shared-lib-node/README.md

@@ -1 +1,5 @@
-# library
+---
+purpose: WillBooster tools and servers share one implementation of process, file-system, and environment-variable handling instead of each writing its own.
+---
+
+# @willbooster/shared-lib-node

packages/shared-lib-react/README.md

@@ -1 +1,5 @@
+---
+purpose: WillBooster React apps share one implementation of common hooks and components instead of each writing its own.
+---
+
 # @willbooster/shared-lib-react

packages/shared-lib/README.md

@@ -1,3 +1,9 @@
+---
+purpose: WillBooster projects on any JavaScript runtime share one implementation of general-purpose code instead of each writing its own.
+goals:
+  - The package runs on every JavaScript runtime WillBooster uses, with no runtime dependencies.
+---
+
 # @willbooster/shared-lib
 
 `recoverJson(response)` extracts JSON candidates from text and Markdown without runtime dependencies. It repairs common syntax errors and recovers partial strings and containers. Each candidate includes its parsed `value`, serialized `json`, original `start`/`end` offsets, and `repairs` with original UTF-16 offsets. The range includes consumed source, such as trailing whitespace and removed comments; use `json` or `value`, not the source slice, for parsing.

packages/wb/README.md

@@ -1,3 +1,13 @@
+---
+purpose: Developers and AI agents run the same commands in every WillBooster repository, whatever its framework or deploy target.
+goals:
+  - One command verifies, tests, starts, or deploys a project on every stack WillBooster uses.
+  - The output of a failed command is all an AI agent needs to fix the failure.
+  - Commands print to standard output only what an AI agent needs to act on, leaving out everything else.
+nonGoals:
+  - Running on Windows.
+---
+
 # @willbooster/wb
 
 `wb` offers a collection of reusable npm scripts, designed primarily for WillBooster Inc. but with potential utility for other projects as well.

packages/wbfy/README.md

@@ -1,19 +1,22 @@
+---
+purpose: Every WillBooster repository stays on the organization's current conventions without anyone configuring it by hand.
+goals:
+  - Applying `wbfy` to a repository leaves nothing to fix by hand.
+  - Applying `wbfy` again changes nothing.
+  - The agent instructions `wbfy` generates are all the guidance an AI agent needs to work in the repository.
+nonGoals:
+  - Supporting repositories outside WillBooster and WillBoosterLab beyond best effort.
+  - Accepting hand-written, legacy, or third-party variants of the files `wbfy` generates.
+  - Running on Windows.
+---
+
 # wbfy
 
 [![Test](https://github.com/WillBooster/shared/actions/workflows/test.yml/badge.svg)](https://github.com/WillBooster/shared/actions/workflows/test.yml)
 [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
 
 :books::rocket: A tool for applying WillBooster's conventional configurations to npm packages
 
-## Motivation
-
-There are some resources for creating a project with conventional configurations like [Yeoman](https://yeoman.io/), GitHub's Template repository, and starter-kit repositories.
-However, we sometimes faced the cases where we wanted to apply conventional configurations to an existing repository, so we've launch this tool!
-
-## Philosophy
-
-This tool must keep idempotency, i.e., it always yields the same result when a user applies this tool to a project even multiple times.
-
 ## How to Use
 
 Run with Bun >= 1.4.4 or Node.js >= 26 on macOS or Linux. mise must be on `PATH`. The target repository may still pin an older Bun: wbfy installs and activates the managed Node.js and Bun before dependency commands, then checks that the Bun CLI is at least 1.4.4. `bunx @willbooster/wbfy` uses its Bun entry point, including when the target repository still pins Node.js 24. To run the CLI with Node.js, invoke its `bin/wbfy.js` with `node`. After updating `mise.toml`, wbfy uses the pinned Node.js and Bun for dependency installation and cleanup.