doc site

Author: cblanquera

AGENTS.md

@@ -0,0 +1,123 @@
+# AGENTS
+
+## Scope
+
+These instructions apply to the entire repository rooted at this directory.
+
+## Working Directory
+
+- Repository root: `/Users/cblanquera/server/projects/stackpress/ingest`
+- Package workspace: `ingest/`
+- Example workspaces: `examples/*`
+
+## Package Manager
+
+- This project uses `yarn`, not `npm`.
+- Use `yarn` for installs, tests, builds, and workspace commands unless the user explicitly asks for something else.
+- Do not replace documented `yarn` commands with `npm` equivalents.
+
+## Node.js Requirement
+
+- Use Node.js `22` or newer for all installs, builds, tests, and scripts.
+- Prefer the newest available Node.js version when multiple `22.x` or newer versions are installed.
+- If the resolved Node.js version is lower than `22`, stop and switch to a compatible binary before continuing.
+
+## Node.js Resolution Order
+
+When you need a Node.js binary, resolve it in this order and stop at the first successful result:
+
+1. Check whether `nvm` is installed.
+2. If `nvm` is installed, try to locate the `nvm` directory that contains installed Node.js versions.
+3. If the `nvm` directory cannot be located directly, try to use `nvm` itself to resolve a `22+` Node.js version.
+4. If `nvm` is not available or cannot produce a usable binary, check common OS-specific Node.js install paths.
+5. If common paths do not contain Node.js `22+`, inspect environment variables for a Node.js binary path.
+6. If no compatible Node.js binary is found after all checks, stop the task and ask the user for the Node.js location.
+
+## Detailed Node.js Lookup Instructions
+
+### 1. Check for `nvm`
+
+- First check whether `nvm` is available in the shell.
+- If it is available, prefer Node.js binaries managed by `nvm`.
+
+### 2. If `nvm` is available, locate the `nvm` directory
+
+Check these locations and hints first:
+
+- `NVM_DIR`
+- `$HOME/.nvm`
+- `$XDG_CONFIG_HOME/nvm`
+- `$HOME/.config/nvm`
+- Any shell profile entry that exports `NVM_DIR`
+
+Once the directory is found, look for installed Node.js binaries under:
+
+- `<nvm-dir>/versions/node/`
+
+Choose the highest installed version that is `>= 22`.
+
+### 3. If the `nvm` directory cannot be located, use `nvm` directly
+
+Try to resolve Node.js through `nvm` commands instead of hard-coded paths. Prefer flows equivalent to:
+
+- listing installed versions
+- selecting the newest installed `22+` version
+- using `nvm which` for that version
+
+Do not install a new Node.js version unless the user explicitly asks for that.
+
+### 4. If `nvm` is unavailable, check common OS paths
+
+Check common Node.js binary locations for the current OS.
+
+macOS and Linux common paths:
+
+- `/usr/local/bin/node`
+- `/opt/homebrew/bin/node`
+- `/opt/local/bin/node`
+- `/usr/bin/node`
+
+Windows common paths:
+
+- `C:\Program Files\nodejs\node.exe`
+- `C:\Program Files (x86)\nodejs\node.exe`
+
+Version-check any discovered binary and only use it if it is `>= 22`.
+
+### 5. If common paths fail, inspect environment variables
+
+Check environment variables that may expose a Node.js binary or installation root, including:
+
+- `PATH`
+- `NODE_HOME`
+- `NODE_BIN`
+- `NVM_BIN`
+- other obvious project or shell variables that directly point to a Node.js executable
+
+Only accept the result if the resolved binary reports version `22` or newer.
+
+### 6. If still unresolved
+
+- Stop the task.
+- Ask the user to provide the absolute path to a Node.js `22+` binary.
+
+## Execution Rules
+
+- Before running project scripts, confirm that `node --version` is `>= 22`.
+- When a command must use a specific Node.js binary, prefer invoking that binary directly instead of relying on an ambiguous shell `PATH`.
+- Do not downgrade Node.js for compatibility guesses.
+- Do not continue with a lower Node.js version just because commands appear to work.
+
+## Repository Commands
+
+From the repository root:
+
+- Install dependencies: `yarn install`
+- Run tests: `yarn test`
+- Build package: `yarn build`
+
+From the package workspace:
+
+- Install dependencies: `yarn --cwd ingest install`
+- Run tests: `yarn --cwd ingest test`
+- Build package: `yarn --cwd ingest build`

README.md

@@ -17,8 +17,8 @@ Ingest is a lightweight, flexible server framework that brings the familiar Expr
 - **🚀 Serverless-First**: Designed specifically for serverless environments while maintaining compatibility with traditional servers
 - **🔄 Event-Driven**: Built on a robust event system that enables reactive programming patterns
 - **🛣️ Multi-Routing Interface**: Four different routing approaches in one framework
-- **🔌 Plugin System**: Highly extensible with a simple plugin architecture
-- **📦 Build Support**: Exposes routing information for bundlers and build tools
+- **🔌 Plugin System**: Optional automatic wiring for routes, hooks, and shared services
+- **📦 Build Support**: Exposes routing information for build and deployment tooling
 - **🌐 Cross-Platform**: Works with Node.js HTTP, WHATWG Fetch, and various serverless platforms
 
 ## Installation
@@ -91,7 +91,7 @@ app.entry.get('/users', './routes/users.js');
 ```
 
 ### 3. Import Router (Lazy Loading)
-Dynamic imports for code splitting:
+Dynamic imports for lazy loading and tooling-aware route boundaries:
 
 ```typescript
 app.import.get('/users', () => import('./routes/users.js'));
@@ -110,7 +110,7 @@ Ingest can automatically determine which router to use based on your input:
 
 ```typescript
 // Automatically uses action router
-app.get('/users', (req, res) => { /* handler */ });
+app.get('/users', ({ req, res }) => { /* handler */ });
 
 // Automatically uses import router
 app.get('/users', () => import('./routes/users.js'));
@@ -121,14 +121,14 @@ app.get('/users', './views/users.hbs');
 
 ## Plugin System
 
-Ingest features a powerful plugin system that allows you to modularize your application:
+Ingest includes an optional plugin system that can automate application wiring. You can still wire routes, handlers, and services manually in a main file if you prefer:
 
 ### Creating a Plugin
 
 ```typescript
 // src/plugins/auth.ts
 export default function authPlugin(server) {
-  server.on('request', (req, res) => {
+  server.on('request', ({ req, res }) => {
     // Add authentication logic
     if (!req.headers.get('authorization')) {
       res.setError('Unauthorized', {}, [], 401);
@@ -171,12 +171,12 @@ Ingest is built on a powerful event system that allows for reactive programming:
 
 ```typescript
 // Listen to all requests
-app.on('request', (req, res) => {
+app.on('request', ({ req, res }) => {
   console.log(`${req.method} ${req.url.pathname}`);
 });
 
 // Listen to specific routes
-app.on('GET /api/users', (req, res) => {
+app.on('GET /api/users', ({ req, res }) => {
   // This runs for GET /api/users
 });
 
@@ -238,7 +238,7 @@ export const handler = async (event, context) => {
 
 ## Build Support
 
-Ingest exposes routing information that can be used by bundlers and build tools:
+Ingest exposes routing information that can be used by build and deployment tooling:
 
 ```typescript
 const app = server();
@@ -252,17 +252,20 @@ console.log(app.entries);   // File entries
 console.log(app.views);     // View templates
 ```
 
-This information can be used by bundlers to:
+This information can be used by tooling to:
 - Pre-bundle route modules
 - Generate static route manifests
-- Optimize code splitting
+- Discover import, entry, and view boundaries
 - Create deployment artifacts
 
 ## Documentation
 
-- [API Reference](./docs/api/README.md) - Complete API documentation
-- [Examples](./docs/examples.md) - Comprehensive usage examples
-- [Plugin Development](./docs/plugin-development.md) - Guide to creating plugins
+- [Specifications](./specs/README.md) - Documentation index
+- [Overview](./specs/overview.md) - What Ingest is optimizing for
+- [Concepts](./specs/concepts/README.md) - How the system works
+- [Guides](./specs/guides/README.md) - Task-oriented documentation
+- [API Reference](./specs/api/README.md) - Exact class and method lookup
+- [Examples](./specs/examples.md) - Example workspace guide
 
 ## Examples