@sha3/code-standards 0.1.6 → 0.1.7

package/README.md

@@ -117,7 +117,7 @@ After `init`, your new repo contains:
 - `ai/examples/rules/*.ts` (good/bad examples per rule)
 - `ai/examples/demo/src/*` (feature-folder demo with classes and section blocks)
 - `src/config.ts` for centralized hardcoded configuration values
-- `README.md` generated with an icon emoji in the main header
+- `README.md` generated with an icon emoji and complete integration docs (API + config + integration contract for other LLMs)
 - `.gitignore` preconfigured for Node/TypeScript output
 - lint/format/typecheck/test-ready project template
 - `package.json.codeStandards` metadata used by `refresh` (`template`, `profilePath`, `withAiAdapters`, `lastRefreshWith`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sha3/code-standards",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "AI-first code standards, tooling exports, and project initializer",
   "type": "module",
   "bin": {

package/resources/ai/templates/rules/readme.md

@@ -7,6 +7,11 @@ Mandatory requirements:
 - README MUST clearly explain: what the project does, why it exists, and how to use it in under 60 seconds.
 - README MUST include practical copy/paste examples that are runnable.
 - README MUST include a fast path (`TL;DR` or `Quick Start`) and an in-depth reference section.
+- For libraries, README MUST be complete integration documentation for external teams and LLM agents.
+- README MUST include a public API reference section with exported members and behavior expectations.
+- README MUST include a dedicated integration section that shows how to install/import/use from another project.
+- README MUST include a configuration reference section (`src/config.ts`) with meaning of each constant.
+- README MUST include compatibility constraints (runtime, ESM/CJS expectations, TypeScript assumptions).
 - README MUST include a section for AI usage (how to instruct assistants to follow local standards).
 - README MUST avoid vague marketing language and focus on actionable guidance.
 - README MUST be visually structured with clean headings, concise lists, and code blocks.
@@ -16,6 +21,7 @@ Good example characteristics:
 
 - Starts with immediate value and one-command quick start.
 - Shows exact commands and expected flow.
+- Includes public API and integration contract without forcing reader to inspect source files.
 - Includes troubleshooting or FAQ for common confusion points.
 
 Bad example characteristics:

package/standards/readme.md

@@ -3,6 +3,7 @@
 ## Goal
 
 Every repository README MUST be clear, actionable, and visually structured.
+For libraries, README MUST be complete integration documentation because other LLMs will use it as source-of-truth.
 
 ## Mandatory Sections
 
@@ -10,6 +11,11 @@ Every repository README MUST be clear, actionable, and visually structured.
 - TL;DR or Quick Start with copy/paste commands.
 - What it does and why it exists.
 - Setup and usage examples.
+- Installation requirements and exact install command.
+- Public API reference (exports, expected inputs/outputs, and behavior notes).
+- Integration guide (how to consume the library from another project).
+- Configuration reference (`src/config.ts` constants and impact).
+- Compatibility and constraints (runtime, module format, TypeScript expectations).
 - AI workflow section when the repository uses AI coding contracts.
 - Troubleshooting or FAQ.
 
@@ -23,3 +29,4 @@ Every repository README MUST be clear, actionable, and visually structured.
 ## Quality Bar
 
 A top-tier README lets a new engineer understand and run the project in under 5 minutes without asking additional questions.
+For libraries, a top-tier README also lets another LLM integrate the library in a different codebase without opening source files.

package/templates/node-lib/README.md

@@ -1,6 +1,6 @@
 # 📚 {{packageName}}
 
-Libreria TypeScript lista para publicar y reutilizar.
+Reusable TypeScript library with a clear integration contract for external projects and LLM agents.
 
 ## TL;DR
 
@@ -10,28 +10,74 @@ npm run check
 npm run build
 ```
 
-## Uso
+## Installation
+
+```bash
+npm install <library-name>
+```
+
+## Compatibility
+
+- Node.js 20+
+- ESM (`"type": "module"`)
+- Strict TypeScript
+
+## Public API
+
+### `greet(name: string): string`
+
+Returns a greeting using the configured prefix.
 
 ```ts
-import { greet } from "./dist/index.js";
+import { greet } from "<library-name>";
 
-console.log(greet("world"));
+const greeting = greet("world");
+console.log(greeting);
 ```
 
+## Integration Guide (External Projects)
+
+1. Install the library with `npm install <library-name>`.
+2. Import only from the public entrypoint (`<library-name>`).
+3. Do not import internal paths (`src/*`, private `dist/*` files, or private modules).
+4. If you integrate with an LLM, treat this section as the integration contract.
+
+## Configuration (`src/config.ts`)
+
+Hardcoded configuration is centralized in `src/config.ts`.
+
+- `CONFIG.GREETING_PREFIX`: prefix used by `greet`.
+
+## Contract for LLM Integrators
+
+- This README is the source of truth for external integration.
+- The stable API is the one documented in `Public API`.
+- If API shape or observable behavior changes, update this README in the same change.
+
 ## Scripts
 
 - `npm run check`: lint + format check + typecheck + tests
-- `npm run fix`: aplica autofix de lint y prettier
-- `npm run build`: compila a `dist/`
-- `npm run test`: ejecuta tests con Node test runner
+- `npm run fix`: lint/prettier autofix
+- `npm run build`: compile to `dist/`
+- `npm run test`: tests con Node test runner
+
+## Structure
+
+- `src/`: implementation
+- `src/config.ts`: centralized configuration
+- `test/`: tests
+- `dist/`: build output
+
+## Troubleshooting
+
+### Import errors (ESM)
+
+Ensure the consumer project uses Node.js-compatible ESM.
 
-## Estructura
+### Type errors
 
-- `src/`: implementacion
-- `src/config.ts`: configuracion hardcodeada centralizada
-- `test/`: pruebas
-- `dist/`: salida de build
+Run `npm run typecheck` in the consumer project and verify TypeScript version compatibility.
 
 ## AI Workflow
 
-Si trabajas con asistentes, usa `AGENTS.md` y `ai/*.md` como reglas bloqueantes.
+If you work with assistants, treat `AGENTS.md` and `ai/*.md` as blocking rules.

package/templates/node-service/README.md

@@ -1,6 +1,6 @@
 # 🚀 {{packageName}}
 
-Servicio TypeScript listo para ejecutar en local y evolucionar por features.
+TypeScript service template ready for local execution and feature-based evolution.
 
 ## TL;DR
 
@@ -10,27 +10,61 @@ npm run check
 npm run start
 ```
 
-## Ejecucion
+## Run
 
 ```bash
 npm run start
 ```
 
-El servicio arranca por defecto en `http://localhost:3000`.
+The service starts on `http://localhost:3000` by default.
+
+## Compatibility
+
+- Node.js 20+
+- ESM (`"type": "module"`)
+- Strict TypeScript
+
+## API HTTP
+
+### `GET /`
+
+- Response: `200 OK`
+- `content-type`: `application/json`
+- body: `{ "ok": true, "statusSource": "<url>" }`
+
+## Integration Guide (External Projects)
+
+1. Start the service with `npm run start`.
+2. Consume the root endpoint for health/status.
+3. Integrate through the HTTP contract, not through internal files.
+
+## Configuration (`src/config.ts`)
+
+Hardcoded configuration is centralized:
+
+- `CONFIG.RESPONSE_CONTENT_TYPE`
+- `CONFIG.DEFAULT_PORT`
+- `CONFIG.EXTERNAL_STATUS_URL`
+
+## Contract for LLM Integrators
+
+- This README defines the expected HTTP contract.
+- Payload/status/header changes require a README update in the same change.
+- For integration, use documented endpoints and do not assume internal details.
 
 ## Scripts
 
-- `npm run start`: inicia el servicio con `tsx`
+- `npm run start`: start the service with `tsx`
 - `npm run check`: lint + format check + typecheck + tests
-- `npm run fix`: aplica autofix de lint y prettier
-- `npm run test`: ejecuta tests con Node test runner
+- `npm run fix`: apply lint/prettier autofix
+- `npm run test`: run tests with Node test runner
 
-## Estructura
+## Structure
 
-- `src/`: implementacion
-- `src/config.ts`: configuracion hardcodeada centralizada
-- `test/`: pruebas
+- `src/`: implementation
+- `src/config.ts`: centralized hardcoded configuration
+- `test/`: tests
 
 ## AI Workflow
 
-Si trabajas con asistentes, usa `AGENTS.md` y `ai/*.md` como reglas bloqueantes.
+If you work with assistants, treat `AGENTS.md` and `ai/*.md` as blocking rules.