diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..5adcc3516
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Multi-module Gradle build (see `settings.gradle`): AWS adapters (`aws-*`), Lambdas (`lambda-*`, `lambda-*-graalvm`), shared libs (`fkq-*`, `http*`, `strings`), and UI (`console`).
+- Source lives under each module’s `src/main/java` and `src/main/resources`; tests under `src/test/java` with fixtures in `src/test/resources`.
+- Infrastructure templates and assets: `src/main/resources/cloudformation/`, `docs/`, `images/`, `docker/` and `docker-compose*.yml` for local stacks.
+
+## Build, Test, and Development Commands
+- `./gradlew clean build` — compile all modules, generate CloudFormation artifacts, and run unit tests.
+- `./gradlew test` — run tests only; respects `-Ptestregion`, `-Ptestprofile`, `-Ptestappenvironment`, `-Ptestchatgptapikey` when AWS context is required.
+- `./gradlew spotlessCheck` — verify formatting; use `spotlessApply` before pushing.
+- `./gradlew licenseReport` — regenerate license inventory under `docs/licenses/`.
+
+## Coding Style & Naming Conventions
+- Java code formatted via Spotless/Eclipse profile (`spotless.eclipseformat.xml`); let the formatter decide indentation and wrapping.
+- Use descriptive, AWS-aligned names for modules/resources (e.g., `lambda-s3`, `aws-dynamodb`), and keep package names consistent with service boundaries.
+- Prefer immutable data where practical; validate inputs at module edges (API handlers, S3 triggers, event listeners).
+
+## Testing Guidelines
+- Default to JUnit tests in `src/test/java`; mirror package structure of the code under test.
+- When tests hit AWS-dependent flows, supply Gradle properties (`-Ptestregion`, etc.) pointing to sandbox credentials/profiles.
+- Mark slow/integration tests with JUnit tags to allow selective execution (e.g., `./gradlew test -DexcludeTags=integration`).
+- Add fixtures in `src/test/resources`; avoid hardcoding secrets.
+
+## Commit & Pull Request Guidelines
+- Commit messages follow short, imperative summaries and often include issue references (e.g., `#443 - Enable a "Group" for API Keys`).
+- PRs should describe scope, risks, and deployment impacts; link issues/tickets; add screenshots for `console` UI changes.
+- Update docs or CloudFormation templates when behavior or contract changes; note backward-compatibility and migration steps.
+
+## Security & Configuration Tips
+- Do not commit AWS credentials; rely on `~/.aws/credentials` profiles or runtime environment vars.
+- Keep generated CloudFormation outputs reproducible: run Gradle tasks instead of manual edits, and verify hashes produced by `ytt` specs.
diff --git a/README.md b/README.md
index 4ff4d4a2a..c20274046 100644
--- a/README.md
+++ b/README.md
@@ -11,98 +11,77 @@
 
 </div>
 
-## Enterprise-Grade Document Management Layer
-
-FormKiQ is a production-ready document management platform built on AWS serverless infrastructure. Deploy a complete document layer alongside your application's data tier—handling storage, metadata, search, and access control without the complexity of building it yourself.
-
-**Fully deployed in your AWS account** for complete control and security.
-
-<div align="center" style="margin: 30px;">
-<img src="https://raw.githubusercontent.com/formkiq/formkiq-core/master/docs/images/multi-tier-architecture.png" style="width:600px;" alt="Multi-tier architecture diagram" />
-</div>
-
-## Why FormKiQ?
-
-Traditional approaches to document storage create technical debt and operational overhead:
-
-**Database Storage Limitations:**
-- Increased storage costs and database bloat
-- Performance degradation under load
-- Limited access control and audit capabilities
-
-**Raw S3 Storage Gaps:**
-- No built-in metadata management or tagging system
-- Missing full-text search capabilities
-- Lack of fine-grained access controls and versioning
-
-**FormKiQ bridges these gaps** with a complete, API-first document management system built on proven AWS managed services—automatically scaling to handle enterprise workloads.
-
-## Core Features
-
-**Document Management**
-- RESTful API with comprehensive document operations
-- Advanced metadata and custom tagging
-- Full-text search with OCR support
-- Document versioning and audit trails
-
-**Enterprise Ready**
-- Serverless architecture (zero server management)
-- Auto-scales to thousands of concurrent requests
-- Multi-tenant and multi-instance deployment options
-- SOC 2 compatible infrastructure
-
-**Developer Experience**
-- Official SDKs for Java and Python
-- OpenAPI specification for custom integrations
-- Comprehensive documentation and tutorials
-- Web-based UI for document management
+# FormKiQ Core
+
+FormKiQ is a production-ready document management platform built on AWS serverless infrastructure that deployed in **your** AWS account. Deploy a complete API-first document layer alongside your application's data tier—handling storage, metadata, search, and access control without the complexity of building it yourself.
+
+## Who it’s for
+- Teams building secure file workflows that must remain in their AWS accounts.
+- Regulated workloads needing auditability, retention, and least-privilege access.
+- SaaS platforms delivering per-tenant document storage with isolation and signed links.
+- Ops/support teams needing fast search over PDFs and images without custom pipelines.
+
+## Capabilities at a glance
+- Ingest via API Gateway, S3, or email; optional OCR pipeline for images/PDFs.
+- Metadata and tagging for every document plus custom attributes.
+- Full-text/OCR search and filters; show only what each user/tenant should see.
+- Versioning, retention, and audit trails built-in; lifecycle controls via policies.
+- Event hooks via Lambda/SNS/SQS/EventBridge to enrich, classify, notify.
+- SDKs for Java and Python, plus OpenAPI for other languages.
+
+## Why teams choose FormKiQ
+- Data and keys stay in your AWS account; IAM-first access control and audit trails.
+- Built-in metadata/tagging, OCR search, versioning, and retention—no custom boilerplate.
+- Serverless stack that auto-scales; no servers to patch or capacity to size.
+- Multi-tenant ready and SOC 2–aligned design for regulated workloads.
+
+## Common use cases
+- Records and retention vaults for HR, legal, and finance with audit trails and versioning.
+- Intelligent ingestion: drop into S3/email/API, OCR + metadata tagging, and route via events.
+- Compliance-focused file storage where data must remain in your AWS account with IAM-scoped access.
+- Customer/partner file portals with per-tenant isolation and signed access links.
+- Workflow enrichment: trigger Lambdas on uploads to classify, enrich metadata, notify via SNS/SQS/EventBridge.
+- Searchable knowledge stores over PDFs/images for support and operations teams.
+
+## Deployment options
+- Deploy to your AWS account via CloudFormation (Quickstart below).
+- Evaluate in the hosted demo environment (read-only).
+- Inquire about managed workspaces if you prefer a turnkey setup.
 
 ## Quick Start
-
-Get FormKiQ running in your AWS account in minutes:
-
-1. **[Follow our Quickstart Guide](https://docs.formkiq.com/docs/getting-started/quick-start)** - Deploy via CloudFormation
-2. **[Try the Demo](https://explore.tryformkiq.com/)** - Explore features with read-only access
-   - Email: `demo@formkiq.com`
-   - Password: `tryformkiq`
-3. **[Walk through the API](https://docs.formkiq.com/docs/getting-started/api-walkthrough)** - Integration examples
-
-Or **[sign up for a managed workspace](https://formkiq.com)** to evaluate FormKiQ without AWS setup.
+1. **AWS deploy**: [Quickstart Guide](https://docs.formkiq.com/docs/getting-started/quick-start) (CloudFormation).
+2. **Hosted demo**: [Explore](https://explore.tryformkiq.com/) — Email: `demo@formkiq.com`, Password: `tryformkiq`.
+3. **API walkthrough**: [Step-by-step](https://docs.formkiq.com/docs/getting-started/api-walkthrough) to integrate quickly.
+   - Requirements: AWS account, CLI/CloudFormation access, Java/Gradle for local builds.
 
 ## Architecture
-
-FormKiQ leverages AWS serverless services for reliability and scale:
+Serverless on AWS: Lambda + API Gateway + S3 + DynamoDB + OpenSearch, with optional modules for OCR, Typesense, and event handling.
 
 <div align="center" style="margin: 30px;">
 <img src="https://raw.githubusercontent.com/formkiq/formkiq-core/master/docs/images/formkiq_architecture.png" style="width:600px;" alt="FormKiQ architecture diagram" />
 </div>
 
-Built on: Lambda, API Gateway, S3, DynamoDB, OpenSearch, and other AWS managed services.
-
-## Client SDKs
-
-Official SDKs generated from our OpenAPI specification:
-
-- **[Java SDK](https://github.com/formkiq/formkiq-client-sdk-java)** - Full-featured Java client
-- **[Python SDK](https://github.com/formkiq/formkiq-client-sdk-python)** - Pythonic interface for FormKiQ
+## Project structure & commands
+- Modules: `lambda-*` and `lambda-*-graalvm` functions, AWS adapters (`aws-*`), shared libs (`fkq-*`, `http*`, `strings`), console UI (`console`).
+- Templates/assets: `src/main/resources/cloudformation`, `docs/`, `images/`, `docker/`.
+- Build/test: `./gradlew clean build` (full build + tests), `./gradlew test` (tests only), `./gradlew spotlessCheck` (format), `./gradlew licenseReport` (license inventory).
 
-Additional language support available via [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator).
+## Security, compliance, and scale
+- Data, encryption keys, and access policies remain in your AWS account; IAM secures every interaction.
+- Versioning and audit trails support retention and evidence needs for SOC 2/HIPAA-style controls.
+- Serverless footprint scales with demand; designed for thousands of concurrent requests.
 
-## Resources
-
-**Documentation**
-- [Complete Documentation](https://docs.formkiq.com)
-- [API Reference](https://docs.formkiq.com/docs/category/api-reference)
-- [Tutorials](https://docs.formkiq.com/docs/category/tutorials)
-- [How-To Guides](https://docs.formkiq.com/docs/category/how-to)
+## Client SDKs
+- **[Java SDK](https://github.com/formkiq/formkiq-client-sdk-java)** — best for JVM backends.
+- **[Python SDK](https://github.com/formkiq/formkiq-client-sdk-python)** — scripting/data workflows.
+- Other languages via [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator) using the published spec.
 
-**Community & Support**
-- [Blog](https://blog.formkiq.com) - Updates and technical insights
-- [GitHub Issues](https://github.com/formkiq/formkiq-core/issues) - Bug reports and feature requests
-- [Enterprise Support](https://www.formkiq.com/pricing) - Professional support and SLAs
+## Resources & support
+- Docs: [Complete Documentation](https://docs.formkiq.com), [API Reference](https://docs.formkiq.com/docs/category/api-reference), [Tutorials](https://docs.formkiq.com/docs/category/tutorials), [How-To Guides](https://docs.formkiq.com/docs/category/how-to)
+- Updates: [Blog](https://blog.formkiq.com)
+- Issues/questions: [GitHub Issues](https://github.com/formkiq/formkiq-core/issues)
+- Enterprise inquiries: [Contact](mailto:info@formkiq.com) or [formkiq.com](https://www.formkiq.com/pricing)
 
 ## License
 
-MIT License - © 2020-2025 FormKiQ, Inc.
-
-See [LICENSE](LICENSE.txt) for full details.
\ No newline at end of file
+MIT License - © 2020-2025 FormKiQ, Inc. See [LICENSE](LICENSE.txt) for full details.