Add CI/CD and development guides

Author: m-prosper-10

README.md

@@ -151,6 +151,13 @@ npm run dev
 npm test
 ```
 
+## Developer Docs
+
+- Contribution guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Local development: [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md)
+- Architecture: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+- CI / CD: [docs/CI_CD.md](./docs/CI_CD.md)
+
 ## Project Structure
 
 ```text

docs/CI_CD.md

@@ -0,0 +1,86 @@
+# CI / CD Guide
+
+This repository ships with GitHub Actions workflows for quality, security, Docker validation, and GHCR publishing.
+
+## Workflows
+
+### CI
+
+File:
+
+- `.github/workflows/ci.yml`
+
+Behavior:
+
+- installs dependencies
+- runs `npm run build`
+- runs `npm test`
+- runs a CLI `--help` smoke test
+- runs `npm pack --dry-run`
+
+### Security
+
+File:
+
+- `.github/workflows/security.yml`
+
+Behavior:
+
+- dependency review on pull requests
+- `npm audit` checks
+- CodeQL analysis
+- Trivy filesystem scan with SARIF upload
+
+### Docker
+
+File:
+
+- `.github/workflows/docker.yml`
+
+Behavior:
+
+- validates Docker builds on pull requests
+- runs Trivy image scan on PR builds
+- pushes images to GHCR on `main`, `master`, and version tags
+
+## Container Image
+
+Files:
+
+- `Dockerfile`
+- `.dockerignore`
+
+The image builds the CLI in a builder stage and ships a runtime image that executes:
+
+```bash
+node dist/cli.js
+```
+
+## GHCR Publishing
+
+Published image name:
+
+```text
+ghcr.io/<owner>/<repo>
+```
+
+Tags are generated from:
+
+- branch refs
+- git tags
+- commit SHA
+- `latest` on the default branch
+
+## Local Validation Before Push
+
+```bash
+npm test
+npm run build
+docker build -t start-it-cli:local .
+```
+
+## When Updating Workflows
+
+- keep local build/test commands aligned with CI
+- avoid adding checks that the repo cannot satisfy locally
+- document new workflow expectations in this file

docs/DEVELOPMENT.md

@@ -0,0 +1,87 @@
+# Development Guide
+
+This document covers local development workflow for `start-it-cli`.
+
+## Prerequisites
+
+- Node.js 18+ recommended
+- npm
+
+## Install
+
+```bash
+npm install
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+This compiles TypeScript from `src/` into `dist/`.
+
+## Run Locally
+
+Interactive mode:
+
+```bash
+npm run dev
+```
+
+Command-driven examples:
+
+```bash
+npm run dev -- my-app --stack react-vite --yes
+```
+
+```bash
+npm run dev -- fire_extinguisher_ms --app-type backend --stack python-fastapi --path /tmp --yes
+```
+
+## Test
+
+```bash
+npm test
+```
+
+The test suite validates generated project structure and generated guidance artifacts.
+
+## Common Workflow
+
+1. Update prompt, config, or generation logic.
+2. Run `npm test`.
+3. Run `npm run build`.
+4. Update user-facing docs if CLI behavior changed.
+
+## Where To Work
+
+- `src/cli.ts`
+  - CLI parsing and prompts
+- `src/workflow.ts`
+  - available app types and stacks
+- `src/generator.ts`
+  - generation routing
+- `src/templates/`
+  - backend builders and older static templates
+- `src/frontend/`
+  - frontend scaffolders
+- `src/aiml/`
+  - AI/ML scaffolders
+- `src/dsa/`
+  - DSA scaffolders
+- `src/agent/`
+  - AI guidance composition
+
+## Packaging Smoke Check
+
+```bash
+npm pack --dry-run
+```
+
+## Docker Smoke Check
+
+```bash
+docker build -t start-it-cli:local .
+docker run --rm start-it-cli:local --help
+```