.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..6d6890b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,70 @@
+# Contributing to Shasta
+
+Thanks for your interest in contributing. Shasta is a multi-cloud compliance
+and AI governance toolkit — keeping it correct is more important than keeping
+it big, so the bar on PRs is "does this stay honest under the integrity
+tests." This page tells you how to stay green.
+
+## Read this first
+
+Shasta's engineering rules live in [`ENGINEERING_PRINCIPLES.md`](./ENGINEERING_PRINCIPLES.md).
+Read it once before your first PR. The 8 most load-bearing rules are inlined
+at the top of [`CLAUDE.md`](./CLAUDE.md) so they're in context at every
+Claude Code session.
+
+Short version: numbers in docs are tests; no stub functions; multi-region by
+default; framework controls on `Finding`, not in description strings; zero
+LLM calls in the detection path; `NOT_ASSESSED` vs `NOT_APPLICABLE` vs
+`FAIL` used correctly; walkers beat N near-duplicate checks.
+
+## Workflow
+
+1. **Open an issue first** using one of the templates in
+ [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE/) —
+ `bug_report`, `feature_request`, or `new_check_proposal` for new
+ check modules. The `new_check_proposal` form encodes the engineering
+ principles at intake so your proposal can't accidentally skip them.
+2. **Branch** with a prefix: `feature/`, `fix/`, `docs/`, or `check/`
+ (for new check modules).
+3. **Commit** using [Conventional Commits](https://www.conventionalcommits.org/):
+ `type(scope): description`. Example: `feat(aws/iam): add root-key age check`.
+4. **Open a PR** — the template in
+ [`.github/pull_request_template.md`](./.github/pull_request_template.md)
+ includes a principles checklist that mirrors `CLAUDE.md`. Every PR must
+ link its issue with `Closes #N`.
+
+## Required tests (must pass locally before PR)
+
+See the **Required tests on every PR** section in
+[`CLAUDE.md`](./CLAUDE.md#required-tests-on-every-pr):
+
+- `pytest tests/test_integrity/` — doc-vs-code drift tests
+- `pytest tests/test_aws/test_aws_sweep_smoke.py` — AWS module smoke tests
+- `pytest tests/test_azure/test_smoke.py` — Azure module smoke tests
+
+These are mechanically enforced by
+[`.github/workflows/integrity.yml`](./.github/workflows/integrity.yml).
+A drift in any numeric claim in `README.md` or `TRUST.md` fails the build
+until either the code is restored or the doc is updated.
+
+## Pre-commit
+
+Run the `/audit` Claude Code skill on staged changes before every non-trivial
+commit. It walks the engineering-principles checklist and reports pass/fail
+per principle, catching doc drift and framework-mapping regressions before
+CI does.
+
+## Reporting vulnerabilities
+
+Vulnerability reports go to `contact@transilience.ai`, not public issues —
+see [`SECURITY.md`](./SECURITY.md).
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](./CODE_OF_CONDUCT.md).
+Enforcement contact: `contact@transilience.ai`.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+MIT License — see [`LICENSE`](./LICENSE).
diff --git a/README.md b/README.md
index 27d1870..da3d984 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,24 @@
-# Shasta + Whitney — Multi-Cloud Compliance & AI Governance Platform
+
+
+# Shasta + Whitney
+
+**Multi-Cloud Compliance & AI Governance, Claude-Native**
+
+AI-native compliance toolkit — SOC 2, ISO 27001, HIPAA, ISO 42001 and EU AI Act
+across AWS and Azure. Through conversation, not dashboards. From the team at [Transilience.ai](https://www.transilience.ai).
[](https://www.transilience.ai)
-[](LICENSE)
-[](https://github.com/transilienceai/shasta/stargazers)
+[](https://github.com/transilienceai/shasta/actions/workflows/integrity.yml)
+[](./LICENSE)
+[](https://www.python.org/downloads/)
+[](https://github.com/transilienceai/shasta/stargazers)
+[](https://claude.com/claude-code)
+
+[Quick Start](#quick-start) · [Skills Reference](#skills-reference) · [Architecture](#architecture) · [TRUST](./TRUST.md) · [Principles](./ENGINEERING_PRINCIPLES.md) · [Contributing](./CONTRIBUTING.md)
-**An AI-native compliance toolkit that enables startup founders to achieve and maintain SOC 2, ISO 27001, HIPAA, ISO 42001, and EU AI Act compliance across AWS and Azure — through conversation, not dashboards. From the team at [Transilience.ai](https://www.transilience.ai).**
+
+
+---
Shasta scans your cloud infrastructure for SOC 2, ISO 27001, HIPAA, ISO 42001, EU AI Act, OWASP LLM Top 10 and more. The standalone Whitney static scanner ([github.com/transilienceai/whitney](https://github.com/transilienceai/whitney)) handles application source-code prompt-injection detection. Together, they cover 13 compliance frameworks, 221 automated checks, and 199 security questionnaire answers — with a web dashboard, 112 Terraform remediation templates, and auditor-grade evidence. Built for founders running <50 employee companies who need compliance without the $30K/year Vanta bill.
@@ -278,9 +292,9 @@ az account show # Note your subscription_id and tenant_id
/policy-gen # Generate 8 SOC 2 policy documents
```
-See [DEPLOYMENT.md](DEPLOYMENT.md) for the complete setup guide including exact IAM permissions.
+See [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md) for the complete setup guide including exact IAM permissions.
-> **You don't need to memorize slash commands.** Shasta and Whitney are AI-native — just describe what you need in plain English inside Claude Code. Say *"Connect to my AWS and run a full SOC 2 gap analysis with remediation Terraform"* and Claude orchestrates everything. See **[CONVERSATIONS.md](CONVERSATIONS.md)** for 15 real conversation examples.
+> **You don't need to memorize slash commands.** Shasta and Whitney are AI-native — just describe what you need in plain English inside Claude Code. Say *"Connect to my AWS and run a full SOC 2 gap analysis with remediation Terraform"* and Claude orchestrates everything. See **[docs/CONVERSATIONS.md](./docs/CONVERSATIONS.md)** for 15 real conversation examples.
---
@@ -689,10 +703,21 @@ At ~860K tokens on Claude Opus across both sessions, the API cost for this entir
```
shasta/
├── CLAUDE.md # Claude Code project instructions
-├── DEPLOYMENT.md # Complete deployment guide
├── README.md # This file
+├── TRUST.md # How to verify the claims
+├── ENGINEERING_PRINCIPLES.md # Load-bearing contributor rules
+├── CONTRIBUTING.md # Contribution workflow
+├── SECURITY.md # Vulnerability reporting
+├── CODE_OF_CONDUCT.md # Contributor Covenant
+├── CHANGELOG.md # Keep-a-Changelog
├── pyproject.toml # Python project configuration
│
+├── docs/ # Secondary docs
+│ ├── DEPLOYMENT.md # Complete deployment guide
+│ ├── VIBE_CODING.md # Build-process essay
+│ ├── CONVERSATIONS.md # Real conversation examples
+│ └── TRIAGE.md # Whitney LLM-as-judge triage guide
+│
├── .claude/skills/ # Claude Code skills (auto-discovered)
│ ├── connect-aws/SKILL.md # AWS connection and validation
│ ├── connect-azure/SKILL.md # Azure connection and validation
@@ -769,7 +794,7 @@ shasta/
│ └── azure-test-env/ # Azure test environment
│ └── main.tf # Azure test resources (compliant + non-compliant)
│
-├── tests/ # pytest test suite (515+ tests)
+├── tests/ # pytest test suite (500+ tests)
│ ├── conftest.py
│ ├── test_aws/
│ │ ├── test_client.py # AWS client tests (moto)
@@ -860,6 +885,17 @@ shasta/
---
+## Contributors
+
+Thanks to everyone who has contributed checks, framework mappings,
+remediation templates, skills, or docs to Shasta + Whitney.
+
+[](https://github.com/transilienceai/shasta/graphs/contributors)
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md) to get started.
+
+---
+
## License
MIT License. See `LICENSE`.
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..1a82ef9
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,42 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Email **`contact@transilience.ai`** with a description, reproduction steps,
+and the affected Shasta or Whitney version. Please do **not** open a public
+GitHub issue for security vulnerabilities.
+
+## SLA
+
+| Stage | Target |
+|---|---|
+| Acknowledgement | within 48 hours |
+| Status update | within 7 days |
+| Fix or mitigation | within 30 days |
+
+## Scope
+
+**In scope**
+
+- Vulnerabilities in Shasta or Whitney source code.
+- Supply-chain or CI/CD issues in this repository (e.g. compromised
+ workflows in `.github/workflows/`).
+- Vulnerabilities in published artifacts (PyPI packages, release tarballs).
+- Data-exposure issues in the optional dashboard (`shasta[dashboard]`) or
+ trust-center generator.
+
+**Out of scope**
+
+- Compliance findings Shasta reports against your own cloud account —
+ those are the intended product output, not Shasta vulnerabilities. Open
+ a normal issue.
+- Vulnerabilities in third-party cloud services Shasta scans (AWS, Azure).
+ Report those to the respective provider.
+- Vulnerabilities in dependencies that do not affect Shasta's actual use
+ of them. (Still appreciated, just lower priority.)
+
+## Disclosure
+
+We credit reporters in the fix commit and in `CHANGELOG.md` unless the
+reporter requests anonymity. For high-severity issues we also publish a
+GitHub advisory (`gh advisory create`).
diff --git a/CONVERSATIONS.md b/docs/CONVERSATIONS.md
similarity index 100%
rename from CONVERSATIONS.md
rename to docs/CONVERSATIONS.md
diff --git a/DEPLOYMENT.md b/docs/DEPLOYMENT.md
similarity index 100%
rename from DEPLOYMENT.md
rename to docs/DEPLOYMENT.md
diff --git a/VIBE_CODING.md b/docs/VIBE_CODING.md
similarity index 100%
rename from VIBE_CODING.md
rename to docs/VIBE_CODING.md
diff --git a/pyproject.toml b/pyproject.toml
index 7390900..9d3572e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -2,7 +2,37 @@
name = "shasta"
version = "1.8.0"
description = "Multi-cloud compliance and AI governance platform — SOC 2, ISO 27001, HIPAA, ISO 42001, and EU AI Act"
+readme = "README.md"
requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Transilience AI" }]
+keywords = [
+ "compliance",
+ "soc2",
+ "iso27001",
+ "hipaa",
+ "iso42001",
+ "eu-ai-act",
+ "aws",
+ "azure",
+ "security",
+ "cloud-security",
+ "ai-governance",
+ "claude-code",
+ "cspm",
+]
+classifiers = [
+ "Development Status :: 4 - Beta",
+ "Intended Audience :: Developers",
+ "Intended Audience :: System Administrators",
+ "License :: OSI Approved :: MIT License",
+ "Operating System :: OS Independent",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Topic :: Security",
+ "Topic :: System :: Systems Administration",
+]
dependencies = [
"boto3>=1.35.0",
"rich>=13.9.0",
@@ -11,6 +41,12 @@ dependencies = [
"pydantic>=2.9.0",
]
+[project.urls]
+Homepage = "https://github.com/transilienceai/shasta"
+Repository = "https://github.com/transilienceai/shasta"
+Issues = "https://github.com/transilienceai/shasta/issues"
+Changelog = "https://github.com/transilienceai/shasta/blob/main/CHANGELOG.md"
+
[project.optional-dependencies]
azure = [
"azure-identity>=1.17.0",