docs: add real spec docs (PRD, FR, ADR, CLAUDE.md)

ADR.md

@@ -0,0 +1,73 @@
+# ADR — BytePort
+
+## ADR-001 — NVMS/BytePort IaC Manifest Format
+
+**Status:** Accepted
+
+**Context:** Need a single-file format to describe multi-service applications and their AWS infrastructure requirements.
+
+**Decision:** Use a custom NVMS manifest format (`.nvms` / `odin.nvms`) as the primary IaC definition file.
+
+**Rationale:** NVMS provides a project-specific, concise manifest structure tailored to BytePort's deployment model. Avoids full Terraform/CloudFormation verbosity for portfolio-scale deployments.
+
+**Alternatives Considered:**
+- Terraform HCL: powerful but heavyweight for portfolio use cases
+- Docker Compose: container-focused, not IaC for cloud provisioning
+- Pulumi: programmatic but adds runtime dependency
+
+---
+
+## ADR-002 — AWS as Primary Deployment Target
+
+**Status:** Accepted
+
+**Context:** Need a cloud provider for hosting deployed portfolio projects.
+
+**Decision:** Target AWS as the sole cloud provider for v1.
+
+**Rationale:** Widest service coverage. Credentials via standard `~/.aws/credentials` or env vars. EC2, ECS, and Lambda cover the deployment patterns needed for portfolio projects.
+
+**Alternatives Considered:**
+- GCP: less familiar IAM model
+- Azure: Windows-centric toolchain
+- Fly.io / Railway: simpler but less control
+
+---
+
+## ADR-003 — Go Backend + Web Frontend Architecture
+
+**Status:** Accepted
+
+**Context:** Platform needs both a server-side deployment engine and a user-facing management frontend.
+
+**Decision:** Go for the backend deployment engine (`backend/`), web frontend (`frontend/`) for management UI.
+
+**Rationale:** Go provides excellent AWS SDK support and concurrency for running parallel deployment tasks. Web frontend decouples UI iteration from backend logic.
+
+---
+
+## ADR-004 — LLM-Assisted Portfolio Template Generation
+
+**Status:** Accepted
+
+**Context:** Generated portfolio widgets need human-readable descriptions and well-structured content, not just raw API data.
+
+**Decision:** Integrate an LLM (OpenAI ChatGPT as default, LLaMA as local alternative) to enhance generated portfolio component text.
+
+**Rationale:** LLMs can produce compelling project summaries from structured data. Two-backend strategy (cloud + local) avoids hard dependency on paid APIs.
+
+**Alternatives Considered:**
+- Template strings only: functional but produces generic copy
+- Human-written descriptions: requires manual work per project, defeats automation goal
+
+---
+
+## ADR-005 — CLI-First Interface
+
+**Status:** Accepted
+
+**Context:** Developers interact with BytePort primarily during deployment workflows in their terminal.
+
+**Decision:** CLI is the primary interface. Web UI is secondary for status/monitoring.
+
+**Rationale:** CLI fits naturally into existing developer workflows and CI/CD pipelines. Scriptable and composable.

CLAUDE.md

@@ -1,25 +1,48 @@
-# BytePort
+# BytePort — CLAUDE.md
 
-Infrastructure-as-code (IAC) deployment and UX generation platform for software developer portfolios. Reads an IAC file defining application structure, deploys from GitHub to AWS, and auto-generates portfolio site templates via LLM.
+## Project Summary
+
+BytePort is an IaC deployment + portfolio UX generation platform. Developers define their app and AWS infrastructure in a single NVMS manifest; BytePort deploys to AWS and generates portfolio site components showcasing the deployed projects. Optionally uses an LLM (OpenAI or LLaMA) for enhanced template text.
 
 ## Stack
-- Language: Go (backend), TypeScript/JavaScript (frontend)
-- Key deps: AWS SDK, GitHub API, OpenAI/LLM client
-- Structure: `backend/` + `frontend/` monorepo
+
+| Layer | Technology | Notes |
+|-------|-----------|-------|
+| Backend | Go | Deployment engine, AWS SDK, LLM integration |
+| Frontend | Web (see frontend/) | Management UI |
+| IaC Format | NVMS manifest | Custom .nvms format |
+| Cloud | AWS | EC2, ECS, Lambda |
+| LLM | OpenAI / LLaMA | Template text generation |
 
 ## Structure
-- `backend/`: Go server handling IAC parsing, AWS deployment, LLM integration
-- `frontend/`: Portfolio site frontend (TypeScript)
-- `start` / `start.bat`: Dev startup scripts
-
-## Key Patterns
-- IAC-driven: single config file defines application + infra
-- AWS deployment (EC2/ECS/Lambda depending on app type)
-- LLM-generated portfolio widgets and object templates
-- GitHub repo as the source of truth for app code
-
-## Adding New Functionality
-- Backend logic: `backend/` (Go modules)
-- Frontend components: `frontend/`
-- New IAC resource types: extend the IAC parser in `backend/`
-- Run `./start` for local development
+
+```
+backend/
+  byteport/      # Core deployment engine
+  bytebridge/    # Bridge/integration layer
+frontend/        # Management UI
+start            # Local dev startup script
+odin.nvms        # Example NVMS manifest
+```
+
+## Key Commands
+
+```bash
+./start          # Start local dev stack
+go build ./...   # Build all Go packages
+go test ./...    # Run tests
+```
+
+## Development Rules
+
+- All CLI errors MUST print to stderr and exit non-zero
+- AWS credentials read from env vars or ~/.aws/credentials -- never hardcoded
+- New CLI commands go in backend/byteport/cmd/
+- LLM integration is pluggable via LLMBackend interface
+- Manifest parsing is strictly validated -- fail loudly on schema errors
+
+## Quality Gates
+
+- go build ./... -- 0 errors required
+- go vet ./... -- 0 warnings required
+- go test ./... -- all pass required

FUNCTIONAL_REQUIREMENTS.md

@@ -0,0 +1,40 @@
+# Functional Requirements — BytePort
+
+## FR-MANIFEST — IaC Manifest
+
+| ID | Requirement | Traces To |
+|----|-------------|-----------|
+| FR-MANIFEST-001 | The system SHALL parse a BytePort/NVMS manifest file defining app structure and infra | E1.1 |
+| FR-MANIFEST-002 | The system SHALL validate the manifest against a defined schema and fail loudly on errors | E1.1 |
+| FR-MANIFEST-003 | The manifest SHALL support defining multiple services within a single file | E1.2 |
+| FR-MANIFEST-004 | Each service definition SHALL include: name, runtime, port, source repo reference | E1.2 |
+
+## FR-DEPLOY — AWS Deployment
+
+| ID | Requirement | Traces To |
+|----|-------------|-----------|
+| FR-DEPLOY-001 | The system SHALL provision AWS infrastructure described in the manifest | E2.1 |
+| FR-DEPLOY-002 | Provisioned resources SHALL be visible in the AWS console after a successful deploy | E2.1 |
+| FR-DEPLOY-003 | The system SHALL pull application source code from the specified GitHub repository | E2.2 |
+| FR-DEPLOY-004 | Source pull SHALL use the branch or ref specified in the manifest | E2.2 |
+| FR-DEPLOY-005 | The system SHALL output live endpoint URLs on successful deployment | E2.3 |
+| FR-DEPLOY-006 | The system SHALL report per-service deployment status (success/failure/pending) | E2.3 |
+
+## FR-PORTFOLIO — Portfolio UX Generation
+
+| ID | Requirement | Traces To |
+|----|-------------|-----------|
+| FR-PORTFOLIO-001 | The system SHALL generate portfolio site component templates for each deployed project | E3.1 |
+| FR-PORTFOLIO-002 | Generated templates SHALL include live endpoint URLs | E3.2 |
+| FR-PORTFOLIO-003 | Generated templates SHALL provide UI widgets for interaction with the deployed project | E3.2 |
+| FR-PORTFOLIO-004 | LLM-assisted text generation SHALL enhance template descriptions | E3.3 |
+| FR-PORTFOLIO-005 | LLM integration SHALL support both OpenAI (ChatGPT) and local (LLaMA) backends | E3.3 |
+
+## FR-CLI — CLI Interface
+
+| ID | Requirement | Traces To |
+|----|-------------|-----------|
+| FR-CLI-001 | The `byteport deploy` command SHALL trigger the full deploy + portfolio generation pipeline | E4.1 |
+| FR-CLI-002 | The `byteport status` command SHALL display health and endpoint for each deployed service | E4.2 |
+| FR-CLI-003 | All CLI errors SHALL print a clear message to stderr and exit non-zero | E4.1 |
+| FR-CLI-004 | The CLI SHALL read AWS credentials from environment variables or ~/.aws/credentials | E4.1 |

PRD.md

@@ -0,0 +1,43 @@
+# PRD — BytePort
+
+## Overview
+
+BytePort is an Infrastructure-as-Code (IaC) deployment and UX generation platform for software developer portfolios. Developers define their application and infrastructure in a single IaC manifest; BytePort deploys the project to AWS and generates interactive portfolio site templates to showcase and provide access to the deployed projects.
+
+## Epics
+
+### E1 — IaC Manifest Parsing
+
+| Story | Description | Acceptance Criteria |
+|-------|-------------|---------------------|
+| E1.1 | Developer writes a single NVMS/BytePort manifest describing app structure and infra | Manifest parses without errors; schema is validated |
+| E1.2 | Manifest supports multi-service applications | Each service definition maps to a distinct deployable unit |
+
+### E2 — AWS Deployment
+
+| Story | Description | Acceptance Criteria |
+|-------|-------------|---------------------|
+| E2.1 | BytePort reads manifest and provisions AWS resources | EC2/ECS/Lambda resources appear in AWS console after deploy |
+| E2.2 | Deployment pulls source from GitHub repository | Correct branch/ref is deployed to target infrastructure |
+| E2.3 | BytePort reports deployment status and endpoint URLs | CLI outputs live URLs on success |
+
+### E3 — Portfolio UX Generation
+
+| Story | Description | Acceptance Criteria |
+|-------|-------------|---------------------|
+| E3.1 | BytePort generates portfolio site components for deployed projects | Object templates are emitted for addition to portfolio sites |
+| E3.2 | Generated components provide interaction access to deployed project | Live project endpoints are embedded in portfolio widget |
+| E3.3 | AI-assisted template generation (ChatGPT/LLaMA) | LLM enhances generated template text and descriptions |
+
+### E4 — CLI Interface
+
+| Story | Description | Acceptance Criteria |
+|-------|-------------|---------------------|
+| E4.1 | Developer runs `byteport deploy` to trigger full pipeline | Single command completes deploy + portfolio generation |
+| E4.2 | Developer runs `byteport status` to check deployments | Output shows per-service health and endpoint |
+
+## Non-Goals
+
+- Multi-cloud (Azure, GCP) in v1
+- Custom domain management
+- Billing/cost management UI