docs: enhance godoc comments, README documentation and add comprehensive AWS deployment guide

.circleci/config.yml

@@ -27,12 +27,11 @@ jobs:
               echo "${RES}"
               exit 1
             fi
-      - run:
-          name: Install golangci-lint
-          command: curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.6.0
       - run:
           name: GolangCI Lint
-          command: golangci-lint run --timeout 300s
+          command: |
+            golangci-lint --version
+            golangci-lint run --verbose
       - save_cache: &save-cache
           paths:
             - /home/circleci/go/pkg/mod

.github/copilot-instructions.md

@@ -5,15 +5,15 @@ Always reference these instructions first and fallback to search or bash command
 ## Working Effectively
 
 ### Bootstrap and Dependencies
-- Install Go 1.25+: `go version` must show go1.25 or later
+- Install Go 1.25.1+: `go version` must show go1.25.1 or later
 - Install Docker: Required for Vault development server
 - Install CLI tools for testing:
   ```bash
   # Ubuntu/Debian
   sudo apt-get update && sudo apt-get install -y curl jq
 
   # Check installations
-  go version    # Must be 1.25+
+  go version    # Must be 1.25.1+
   docker --version
   curl --version
   jq --version
@@ -22,7 +22,7 @@ Always reference these instructions first and fallback to search or bash command
 ### Download Dependencies and Build
 - Download Go modules: `go mod download` -- takes 1-2 minutes. NEVER CANCEL. Set timeout to 180+ seconds.
 - Build binary: `go build -o sup3rs3cret cmd/sup3rS3cretMes5age/main.go` -- takes <1 second after dependencies downloaded.
-- Install linter: `curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v1.64.8` -- takes 30-60 seconds.
+- Install linter: `curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.7.2` -- takes 30-60 seconds. Current system has v2.7.2.
 
 ### Testing and Validation
 - Run tests: `make test` -- takes 2-3 minutes. NEVER CANCEL. Set timeout to 300+ seconds.
@@ -51,17 +51,39 @@ The application will start on port 8080. Access at http://localhost:8080
 docker stop vault-dev && docker rm vault-dev
 ```
 
-### Docker Build Issues
-**IMPORTANT**: Docker builds currently fail in CI/containerized environments due to certificate verification issues with Go proxy:
-```
-go: cloud.google.com/[email protected]: Get "https://proxy.golang.org/...": tls: failed to verify certificate: x509: certificate signed by unknown authority
+### Docker Build and Deployment
+The project includes comprehensive Docker support:
+
+#### Local Development with Docker Compose
+```bash
+# Start full stack (Vault + App on port 8082)
+make run
+# or
+docker compose -f deploy/docker-compose.yml up --build -d
+
+# View logs
+make logs
+
+# Stop services
+make stop
+
+# Clean up
+make clean
 ```
 
-Do NOT attempt Docker builds (`make build`, `make image`, `docker compose up --build`) in sandboxed environments. These commands will fail after 15-30 seconds. Use local Go builds instead.
+The default `docker-compose.yml` runs the app on port 8082 (HTTP) with Vault using token `supersecret`.
+
+#### Production Docker Image
+```bash
+# Build multi-platform image with attestations
+make image
+# Builds for linux/amd64 and linux/arm64 with SBOM and provenance
 
-If you need to test Docker functionality, run individual commands:
-- `make build` -- WILL FAIL in CI. Takes 15-30 seconds to fail.
-- `make image` -- WILL FAIL in CI. Takes 15-30 seconds to fail.
+# Alternative: Build local image only
+docker compose -f deploy/docker-compose.yml build
+```
+
+**Note**: In some CI/containerized environments, Docker builds may encounter certificate verification issues with Go proxy. If this occurs, use local Go builds instead.
 
 ## Validation
 
@@ -100,6 +122,16 @@ Always run these commands before committing:
 
 ## Common Tasks
 
+### Key Application Features
+- **Self-Destructing Messages**: Messages are automatically deleted after first read
+- **Vault Backend**: Uses HashiCorp Vault's cubbyhole for secure temporary storage
+- **TTL Support**: Configurable time-to-live (default 48h, max 168h/7 days)
+- **File Upload**: Support for file uploads with base64 encoding (max 50MB)
+- **One-Time Tokens**: Vault tokens with exactly 2 uses (1 to create, 1 to read)
+- **Rate Limiting**: 10 requests per second to prevent abuse
+- **TLS Support**: Auto TLS via Let's Encrypt or manual certificate configuration
+- **No External Dependencies**: All JavaScript/fonts self-hosted for privacy
+
 ### Configuration Environment Variables
 - `VAULT_ADDR`: Vault server address (e.g., `http://localhost:8200`)
 - `VAULT_TOKEN`: Vault authentication token (e.g., `supersecret` for dev)
@@ -114,22 +146,45 @@ Always run these commands before committing:
 ### Repository Structure
 ```
 .
-├── cmd/sup3rS3cretMes5age/main.go  # Application entry point
+├── cmd/sup3rS3cretMes5age/
+│   └── main.go                     # Application entry point (23 lines)
 ├── internal/                       # Core application logic
-│   ├── config.go                   # Configuration handling
-│   ├── handlers.go                 # HTTP request handlers  
-│   ├── server.go                   # Web server setup
-│   └── vault.go                    # Vault integration
+│   ├── config.go                   # Configuration handling (77 lines)
+│   ├── handlers.go                 # HTTP request handlers (88 lines)
+│   ├── handlers_test.go            # Handler unit tests (87 lines)
+│   ├── server.go                   # Web server setup (94 lines)
+│   ├── vault.go                    # Vault integration (174 lines)
+│   └── vault_test.go               # Vault unit tests (66 lines)
 ├── web/static/                     # Frontend assets (HTML, CSS, JS)
+│   ├── index.html                  # Main page (5KB)
+│   ├── getmsg.html                 # Message retrieval page (7.8KB)
+│   ├── application.css             # Styling (2.3KB)
+│   ├── clipboard-2.0.11.min.js     # Copy functionality (9KB)
+│   ├── montserrat.css              # Font definitions
+│   ├── robots.txt                  # Search engine rules
+│   ├── fonts/                      # Self-hosted Montserrat font files
+│   └── icons/                      # Favicon and app icons
 ├── deploy/                         # Docker and deployment configs
-│   ├── Dockerfile                  # Container build (fails in CI)
-│   ├── docker-compose.yml          # Local development stack
-│   └── charts/                     # Helm charts for Kubernetes
-├── Makefile                        # Build automation
-├── go.mod                          # Go module definition
-└── README.md                       # Project documentation
-```
-
+│   ├── Dockerfile                  # Multi-stage container build
+│   ├── docker-compose.yml          # Local development stack (Vault + App)
+│   └── charts/supersecretmessage/  # Helm c(lint + test pipeline)
+.codacy.yml        # Code quality config
+.dockerignore      # Docker ignore patterns
+.git/              # Git repository data
+.github/           # GitHub configuration (copilot-instructions.md)
+.gitignore         # Git ignore patterns
+CLI.md             # Command-line usage guide (313 lines, Bash/Zsh/Fish examples)
+CODEOWNERS         # GitHub code owners
+LICENSE            # MIT license
+Makefile           # Build targets (test, image, build, run, logs, stop, clean)
+Makefile.buildx    # Advanced buildx targets (multi-platform, AWS ECR)
+README.md          # Main documentation (176 lines)
+cmd/               # Application entry points
+deploy/            # Deployment configurations (Docker, Helm)
+go.mod             # Go module file (go 1.25.1)
+go.sum             # Go dependency checksums
+internal/          # Internal packages (609 lines total)
+web/               # Web assets (static HTML, CSS, JS, fonts, icons)
 ### Frequently Used Commands Output
 
 #### Repository Root Files
@@ -157,14 +212,14 @@ web/               # Web assets
 ```go
 module github.com/algolia/sup3rS3cretMes5age
 
-go 1.25
+go 1.25.1
 
 require (
-    github.com/hashicorp/vault v1.16.3
-    github.com/hashicorp/vault/api v1.14.0
+    github.com/hashicorp/vault v1.21.0
+    github.com/hashicorp/vault/api v1.22.0
     github.com/labstack/echo/v4 v4.13.4
-    github.com/stretchr/testify v1.10.0
-    golang.org/x/crypto v0.40.0
+    github.com/stretchr/testify v1.11.1
+    golang.org/x/crypto v0.45.0
 )
 ```
 
@@ -195,8 +250,8 @@ o() {
 ### Troubleshooting
 
 **"go: ... tls: failed to verify certificate"**
-- This occurs in Docker builds in CI environments
-- Use local Go builds instead: `go build cmd/sup3rS3cretMes5age/main.go`
+- This may occur in Docker builds in some CI environments
+- Solution: Use local Go builds instead: `go build -o sup3rs3cret cmd/sup3rS3cretMes5age/main.go`
 
 **"jq: command not found"**
 ```bash
@@ -216,3 +271,48 @@ brew install jq
 - Tests create their own Vault instances
 - Verbose logging is normal (200+ lines per test)
 - NEVER CANCEL tests - they clean up automatically
+
+**Port 8082 already in use**
+```bash
+# Find what's using the port
+sudo lsof -i :8082
+# or
+sudo netstat -tulpn | grep 8082
+
+# Stop docker-compose if running
+make stop
+```
+
+**Build fails with "cannot find package"**
+```bash
+# Clean Go module cache and re-download
+go clean -modcache
+go mod download
+```
+
+### Makefile Targets Reference
+```bash
+make test          # Run all unit tests (takes 2-3 min)
+make image         # Build multi-platform Docker image with attestations
+make build         # Build Docker image via docker-compose
+make run           # Start docker-compose stack (Vault + App on :8082)
+make run-local     # Clean and start docker-compose
+make logs          # Tail docker-compose logs
+make stop          # Stop docker-compose services
+make clean         # Remove docker-compose containers
+```
+
+### CircleCI Pipeline
+The project uses CircleCI with two jobs:
+1. **lint**: Format checking (gofmt), golangci-lint v2.6.0
+2. **test**: Unit tests via `make test`
+
+Pipeline runs on Go 1.25 docker image (`cimg/go:1.25`).
+
+### Helm Deployment
+Helm chart located in `deploy/charts/supersecretmessage/`:
+- Chart version: 0.1.0
+- App version: 0.2.5
+- Includes: Deployment, Service, Ingress, HPA, ServiceAccount
+- Configurable: Vault connection, TLS settings, resource limits
+- See [deploy/charts/README.md](deploy/charts/README.md) for details

.golangci.yml

@@ -0,0 +1,6 @@
+# Config format version
+version: 2
+
+run:
+  concurrency: 1
+  timeout: 8m