docs: expand Configuration with flags/validation & tabbed snippets

Author: zonayedpca

docs/_meta.json

@@ -2,6 +2,6 @@
   "name": "StatikAPI",
   "description": "Build static JSON endpoints from filesystem modules — like Next.js static export, but for APIs.",
   "version": "0.4.0",
-  "lastUpdated": "2025-11-08T00:30:00.000Z",
+  "lastUpdated": "2025-11-08T00:40:00.000Z",
   "repo": "https://github.com/zonayedpca/statikapi"
 }

docs/cli.mdx

@@ -1,16 +1,151 @@
 # Configuration
 
-Most projects work with **zero config**. When you need to customize directories, add `statikapi.config.js` at the project root:
+StatikAPI works with **zero config**. When you need to customize paths, create a **`statikapi.config.js`** in your project root.
 
 ```js
 // statikapi.config.js
 export default {
-  srcDir: "src-api",
-  outDir: "api-out"
+  srcDir: 'src-api',
+  outDir: 'api-out',
 };
+```
+
+> Both directories are **relative to the project root**, must be **non-empty strings**, and **cannot be the same path**. Absolute paths and parent traversal (e.g. `../outside`) are not allowed.
+
+---
+
+## Fields
+
+### `srcDir` (string, default: `"src-api"`)
+
+- Folder that contains your **route modules**.
+- Supported extensions: **.js, .mjs, .cjs, .ts, .tsx**.
+- Files/folders that **start with `_`** are ignored (e.g. `_private/`).
+- `index.js` collapses to the folder route (e.g. `blog/index.js` → `/blog`).
+
+### `outDir` (string, default: `"api-out"`)
+
+- Folder where **generated JSON** is written.
+- Each URL path becomes a folder with **`index.json`** inside.
+- A build **manifest** is also written to `api-out/.statikapi/manifest.json` containing route → file mappings and sizes (handy for tooling/preview UIs).
+
+---
+
+## Path resolution & validation
+
+The CLI normalizes and validates configuration:
+
+- Paths are **normalized** with POSIX separators.
+- Must be **relative** (no absolute paths).
+- Must **not traverse** outside the project (no leading `../`).
+- `srcDir` and `outDir` must be **different**.
+
+If validation fails, the CLI throws a helpful **ConfigError** before building.
+
+---
+
+## Override via CLI flags
+
+You can override config values per-invocation. The current CLI reads **`--srcDir`** and **`--outDir`**:
+
+<Tabs group="flags">
+  <Tab label="pnpm">
+
+```bash
+pnpm statikapi build --srcDir api --outDir public/api
+```
+
+  </Tab>
+  <Tab label="yarn">
+
+```bash
+yarn statikapi build --srcDir api --outDir public/api
+```
+
+  </Tab>
+  <Tab label="npm">
+
+```bash
+npx statikapi build --srcDir api --outDir public/api
+```
+
+  </Tab>
+</Tabs>
+
+> Heads‑up: older notes might mention `--src` / `--out`. In the current CLI, use **`--srcDir`** and **`--outDir`** to affect configuration.
+
+---
 
+## Dev server notes
+
+When running **`statikapi dev`**:
+
+- Serves your built files and an interactive UI at `/_ui`.
+- Writes/updates `api-out/.statikapi/manifest.json` on changes.
+- Environment overrides (advanced):
+  - **`STATIKAPI_UI_DIR`** — serve a custom, prebuilt UI directory (must contain `index.html`).
+  - **`STATIKAPI_FORCE_DEV=1`** — keep dev running in non‑TTY environments (e.g., CI runners, `concurrently`).
+
+<Tabs group="dev-flags">
+  <Tab label="pnpm">
+
+```bash
+pnpm statikapi dev --port 8788 --srcDir src-api --outDir api-out
+```
+
+  </Tab>
+  <Tab label="yarn">
+
+```bash
+yarn statikapi dev --port 8788 --srcDir src-api --outDir api-out
+```
+
+  </Tab>
+  <Tab label="npm">
+
+```bash
+npx statikapi dev --port 8788 --srcDir src-api --outDir api-out
+```
+
+  </Tab>
+</Tabs>
+
+---
+
+## Recipes
+
+### 1) Customizing directories
+
+```js
+// statikapi.config.js
+export default {
+  srcDir: 'api', // move sources into /api
+  outDir: 'public/api', // emit static JSON inside your public/ folder
+};
 ```
 
-You can override these from the CLI with `--src` and `--out`.
+### 2) Monorepo (package-local config)
+
+Place `statikapi.config.js` in the **package root** that owns the `srcDir`. The CLI resolves paths **relative to the CWD** (where you run it).
+
+### 3) TypeScript routes
+
+You can freely use **.ts / .tsx** route files. The CLI transpiles on the fly and imports them, then enforces **JSON‑serializable** outputs.
+
+---
+
+## Troubleshooting
+
+- **Config error “must be a relative path”** — remove any leading `/` or drive letter; use relative paths like `src-api`, `api-out`.
+- **“cannot traverse outside the project”** — avoid `../` path segments.
+- **`srcDir` and `outDir` must differ** — point them at different folders.
+- **Dynamic routes not emitting** — ensure the module exports `paths()` that returns **strings** (or arrays of strings for catch‑all). See **Routes** docs.
+- **Non‑serializable value** — only plain objects/arrays, finite numbers, strings, booleans, or `null`. No functions, symbols, BigInt, Dates, classes, or cycles.
+
+---
+
+## See also
 
-> **Tip:** The scaffolders also generate `.nvmrc` and `.node-version` for Node 22, and can drop deploy files like `wrangler.toml`, `netlify.toml`, or a GitHub Pages workflow when selected.
+- **[CLI → StatikAPI (Core)](./cli/statikapi)** for flags and dev/build usage
+- **[Routes](./routes/index)** for file → URL mapping rules
+- **[Deployments](./deployments/index)** for hosting static JSON