@raishin/vanguard-frontier-agentic 1.1.0 → 1.3.0

package/README.md

@@ -1,25 +1,312 @@
-# 🚀 Vanguard Frontier Agentic
+# Vanguard Frontier Agentic
 
-**A friendly, curated marketplace for cloud and zero-trust AI workflows.**
+<div align="center">
+
+  <!-- 🖼️ PROJECT LOGO — created and ready to display -->
+  <img src="assets/logos/vanguard-frontier-agentic-logo.png" alt="Vanguard Frontier Agentic" width="220" />
+
+  <p><strong>A curated marketplace for cloud and zero-trust AI workflows.</strong></p>
+
+  <p>
+    <a href="#get-started">Get Started</a> &nbsp;·&nbsp;
+    <a href="#install-reference">Install Reference</a> &nbsp;·&nbsp;
+    <a href="#skills">Skills</a> &nbsp;·&nbsp;
+    <a href="#agents">Agents</a> &nbsp;·&nbsp;
+    <a href="https://github.com/Raishin/vanguard-frontier-agentic/issues">Issues</a> &nbsp;·&nbsp;
+    <a href="#faq">FAQ</a> &nbsp;·&nbsp;
+    <a href="#feedback">Feedback</a>
+  </p>
+</div>
+
+---
 
 This repo collects reusable **skills**, **agents**, **rules**, **MCP references**,
 and supporting assets for engineers working with AWS, Azure, OCI, GCP,
 Kubernetes, Terraform, cloud security, and compliance-heavy architecture.
 
-Think of it as a toolbox:
-
 - 🧠 **Skills** = step-by-step workflows an AI assistant can follow.
 - 🤖 **Agents** = reusable expert roles for review, architecture, and operations.
 - 📏 **Rules** = durable instructions for a specific AI harness.
 - 🔌 **MCP references** = trusted notes for connecting tools to real systems.
 - 🗂️ **Catalogs** = machine-readable indexes so tools can discover everything.
 
-The goal is simple: **make AI-assisted cloud work safer, reusable,
-compliance-aware, and easier to understand.**
+**Works with:**
+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) &nbsp;·&nbsp;
+[Codex](https://github.com/openai/codex) &nbsp;·&nbsp;
+[GitHub Copilot](https://github.com/features/copilot) &nbsp;·&nbsp;
+[Cursor](https://www.cursor.com/) &nbsp;·&nbsp;
+[Gemini CLI](https://github.com/google-gemini/gemini-cli) &nbsp;·&nbsp;
+[Kiro](https://kiro.dev/) &nbsp;·&nbsp;
+*and any other coding agent.*
+
+> 📦 **Available on npm:** `@raishin/vanguard-frontier-agentic` is published on the public npm registry.
+
+---
+
+## 🚀 Get Started
+
+**Prerequisite:** [Node.js](https://nodejs.org/) 18+
+
+```bash
+# 1️⃣ Install the package
+npm install @raishin/vanguard-frontier-agentic@latest
+
+# 2️⃣ Export agents for your job role into your repo
+npx vfa-export-agents --platform claude-code --role cloud-security-engineer --repo .
+
+# 3️⃣ Open your coding agent and reference the exported agent
+#    "Use kubernetes-rbac-review-agent to audit this RBAC change."
+```
+
+**🗺️ Not sure which role or agent you need?** Jump to the [Install Reference](#install-reference) for the full map.
+
+---
+
+## 🧠 Skills
+
+**138 skills** across AWS, Azure, OCI, Kubernetes, CNCF ecosystem, Terraform, and more.
+
+| Domain             | Count | What they cover                                                                                   |
+| ------------------ | ----: | ------------------------------------------------------------------------------------------------- |
+| 🟧 AWS              |    43 | IAM, EKS, ECS, Lambda, RDS, S3, Cost, DevOps, Bedrock, Security, Live Guards                      |
+| 🟦 Azure            |    32 | AKS, App Service, ARM/Bicep, Key Vault, PIM, Cost, Entra ID, CosmosDB, Live Guards                |
+| 🟥 OCI              |    37 | ADB, OKE, IAM, Vault, Resource Manager, Cost, Networking, Live Guards                             |
+| ☸️ Kubernetes       |     5 | RBAC review, workload identity, PSA, live RBAC/admission/mesh/network/ArgoCD guards, maestro      |
+| 🛡️ Kyverno          |     1 | ClusterPolicy/Policy, PolicyException, failureAction, background scan                             |
+| 🔄 Argo CD          |     1 | AppProject blast-radius, sync impersonation, RollingSync, sync-window                             |
+| 🕸️ Istio            |     1 | Ambient mesh, ztunnel L4 vs waypoint L7, PeerAuthentication, mTLS posture                        |
+| 🐝 Cilium           |     1 | CiliumNetworkPolicy, ClusterMesh trust, 169.254.169.254 egress, WireGuard encryption              |
+| 📡 OpenTelemetry    |     1 | Collector pipeline, memory_limiter, receiver exposure, exporter cardinality, credential handling  |
+| 🟩 Terraform        |     1 | IaC review and plan safety                                                                        |
+
+### 🛡️ Live Guard skills — stop before you break prod
+
+Live-guard skills enforce approval gates and rollback posture for irreversible operations:
+
+**🟦 Azure (7):**
+- `azure-live-aks-rollout-guard` — PDB audit, rollout pause/undo, post-rollout health
+- `azure-live-arm-deployment-stack-guard` — what-if evidence, denySettings, PIM-gated delete
+- `azure-live-app-service-slot-swap-guard` — sticky-setting audit, traffic shifting, swap-back path
+- `azure-live-keyvault-rotation-purge-guard` — rotation policy, soft-delete/purge-protection, PIM gate
+- `azure-live-pim-jit-activation-guard` — eligible assignment audit, MFA gate, JIT revocation
+- `azure-live-cost-budget-action-guard` — budget mutation, GPU SKU policy, quota read-only
+- `azure-live-entra-role-assignment-guard` — permanent role assignment scope/principal audit, PIM-preference enforcement, Guest principal blocking
+
+**🟥 OCI (7):**
+- `oci-live-autonomous-db-lifecycle-guard` — ADB scale/stop/clone/terminate with tag enforcement
+- `oci-live-oke-rollout-guard` — DevOps pipeline approval, PDB audit, rollout pause/undo
+- `oci-live-resource-manager-stack-guard` — plan-before-apply, drift detection, job-lock enforcement
+- `oci-live-vault-key-destruction-guard` — rotation vs. destruction separation, 7–30 day deletion window
+- `oci-live-iam-policy-compartment-guard` — MFA break-glass, dual-approval for tenancy-root changes
+- `oci-live-cost-budget-runaway-guard` — 3-tier budget management, GPU shape gate, ONS alert routing
+- `oci-live-network-security-rule-guard` — Security List/NSG rule capture, 0.0.0.0/0 detection, DB-subnet criticality, Path Analyzer gate
+
+**☸️ Kubernetes (5):**
+- `kubernetes-live-rbac-mutation-guard` — escalate/bind/impersonate verb detection, wildcard blocking, pre-mutation state capture, rollback via YAML backup
+- `kubernetes-live-admission-policy-guard` — Kyverno/VAP mutation blast-radius, failureAction enforcement, PolicyException scope validation
+- `kubernetes-live-mesh-policy-guard` — Istio AuthorizationPolicy/PeerAuthentication traffic impact, PERMISSIVE→STRICT migration gating
+- `kubernetes-live-network-policy-guard` — CiliumNetworkPolicy/NetworkPolicy connectivity impact, metadata service egress blocking
+- `kubernetes-live-argocd-sync-guard` — AppProject blast-radius, sync impersonation identity review, sync-window change gating
+
+### Sample skills
+
+- 🔐 [`skills/aws/aws-iam-least-privilege-review`](skills/aws/aws-iam-least-privilege-review/) — Review AWS IAM policies and reduce unnecessary access.
+- 🟦 [`skills/azure/azure-rbac-review`](skills/azure/azure-rbac-review/) — Review Azure RBAC assignments, scopes, and custom roles.
+- 🟥 [`skills/oci/oci-autonomous-database-architect`](skills/oci/oci-autonomous-database-architect/) — Design and review Oracle Autonomous Database across OCI and multicloud options.
+- 💰 [`skills/finops/finops-cloud-price-advisor`](skills/finops/finops-cloud-price-advisor/) — Fetch live prices from AWS, Azure, and OCI public pricing APIs; estimate costs for live environments or prototypes.
+
+Rule of thumb: if the asset teaches **how to do a repeatable task**, it is a skill.
+
+---
+
+## 🤖 Agents
+
+**141 agents** matching the skill catalog — each agent ships 7 harness adapters and a hardened permission model.
+
+| Provider           | Count | Specialisations                                                                     |
+| ------------------ | ----: | ----------------------------------------------------------------------------------- |
+| 🟧 AWS              |    43 | advisory, execution, live-guard operators                                           |
+| 🟦 Azure            |    32 | advisory, live-guard operators                                                      |
+| 🟥 OCI              |    35 | advisory, live-guard operators                                                      |
+| ☸️ Kubernetes       |     9 | RBAC review, workload identity, PSA, 4 live-guard operators, maestro router         |
+| 🛡️ Kyverno          |     1 | Admission policy review                                                             |
+| 🔄 Argo CD          |     1 | GitOps review                                                                       |
+| 🕸️ Istio            |     1 | Ambient mesh review                                                                 |
+| 🐝 Cilium           |     1 | Network policy review                                                               |
+| 📡 OpenTelemetry    |     1 | Collector config review                                                             |
+| 💰 Multi-cloud      |     1 | FinOps Cloud Price Advisor                                                          |
+| 🟩 Terraform        |     2 | IaC review, maestro                                                                 |
+
+Every agent ships:
+- 📄 `AGENT.md` — harness-neutral contract with guarded response shape
+- 🗂️ `metadata.json` — schema-validated catalog entry
+- 🔌 7 harness adapters — claude-code, codex, copilot, cursor, gemini, kiro-ide, kiro-cli
+
+```text
+agents/
+├── aws/              (43 agents)
+├── azure/            (32 agents)
+├── argocd/           (1 agent — GitOps review)
+├── cilium/           (1 agent — network policy review)
+├── finops/           (1 agent — cross-cloud price advisor)
+├── istio/            (1 agent — ambient mesh review)
+├── kubernetes/       (13 agents — RBAC, workload identity, PSA, pod-spec, ESO, Kubecost, live-guards, maestro)
+├── kyverno/          (1 agent — admission policy review)
+├── oci/              (35 agents)
+├── opentelemetry/    (1 agent — collector config review)
+└── terraform/        (2 agents)
+```
+
+Example:
+
+- 🧱 [`agents/terraform/terraform-reviewer`](agents/terraform/terraform-reviewer/) — Review Terraform modules, plans, provider usage, and state assumptions.
+
+Use an agent when you need a **role with judgment**, not just a checklist.
+
+---
+
+## 📦 Install Reference
+
+Everything you can install, and exactly how to install it. One section, no hunting.
+
+### 🧭 How to pick what to install
+
+```
+🙋 I know my job function               → use --role
+🎯 I know the specific agent I want     → use --agents
+☁️  I work on one cloud provider only    → add --provider to either of the above
+💥 I want everything for a platform     → use --all
+🔍 I don't know what exists yet         → use --list or --list-roles first
+```
+
+---
+
+### 🏷️ Argument reference
+
+| Argument       | Values                                                | Required                                | Description                                          |
+| -------------- | ----------------------------------------------------- | --------------------------------------- | ---------------------------------------------------- |
+| `--platform`   | see table below                                       | ✅ yes (except `--list`, `--list-roles`) | Target AI harness                                    |
+| `--role`       | see role table below                                  | pick one ↓                              | Install all agents for a job role                    |
+| `--agents`     | comma-separated agent IDs                             | pick one ↓                              | Install specific agents by ID                        |
+| `--all`        | —                                                     | pick one ↓                              | Install every agent for the platform                 |
+| `--provider`   | `aws` `azure` `oci` `kubernetes` `terraform` `finops` `kyverno` `argocd` `istio` `cilium` `opentelemetry` | ➕ optional | Narrow `--role` results to one provider |
+| `--repo`       | path                                                  | ➕ optional                              | Target repo root (defaults to current directory)     |
+| `--force`      | —                                                     | ➕ optional                              | Overwrite files that already exist                   |
+| `--list`       | —                                                     | 🔍 standalone                            | Print all agent IDs, providers, and names; then exit |
+| `--list-roles` | —                                                     | 🔍 standalone                            | Print role IDs with agent counts; then exit          |
+
+---
+
+### 🖥️ Platform reference
+
+Each platform writes agent files to a different folder in your repo.
 
-> 📦 **npm status (verified 2026-04-28):** `@raishin/vanguard-frontier-agentic`
-> is **not published yet** on the public npm registry. Check live status with:
-> `npm view @raishin/vanguard-frontier-agentic version`
+| `--platform` value | AI harness                       | Installs into     |
+| ------------------ | -------------------------------- | ----------------- |
+| `claude-code`      | 🤖 Claude Code (Anthropic)        | `.claude/agents/` |
+| `codex`            | ⚡ Codex CLI (OpenAI)             | `.codex/agents/`  |
+| `copilot`          | 🐙 GitHub Copilot / VS Code       | `.github/agents/` |
+| `cursor`           | 🖱️ Cursor                         | `.cursor/agents/` |
+| `gemini`           | ♊ Gemini CLI (Google)            | `.gemini/agents/` |
+| `kiro`             | 🔮 Kiro — both IDE + CLI adapters | `.kiro/agents/`   |
+| `kiro-ide`         | 🔮 Kiro IDE only                  | `.kiro/agents/`   |
+| `kiro-cli`         | 🔮 Kiro CLI only                  | `.kiro/agents/`   |
+
+> ℹ️ The exporter installs agent files only. It does not write repo-level guidance files (`CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, etc.). See [`docs/normalized-platform-matrix.md`](docs/normalized-platform-matrix.md).
+
+---
+
+### 👤 Role reference
+
+A role installs the curated set of agents a practitioner in that job function needs, across all cloud providers. Roles overlap intentionally — one agent may appear in multiple roles.
+
+| `--role` value                               | 👤 Who it is for                                                         | 🔢 Agents | ☁️ What it covers                                                                                                                          |
+| -------------------------------------------- | ------------------------------------------------------------------------ | -------: | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `cloud-security-engineer`                    | 🔐 Security engineers, compliance teams, IAM owners                       |       26 | IAM/RBAC review, secrets lifecycle, identity governance, live guards for access and key mutations — AWS · Azure · OCI · Kubernetes        |
+| `cloud-platform-engineer`                    | 🏗️ Infrastructure/SRE, IaC owners, Kubernetes platform teams              |       25 | IaC safety review, container platform operators, networking, landing zones, live deployment guards — AWS · Azure · OCI · Terraform        |
+| `cloud-dba`                                  | 🗄️ Database administrators, data platform engineers                       |       13 | RDS/Aurora, DynamoDB, CosmosDB, OCI Autonomous/Exadata/MySQL HeatWave, replication, live DB lifecycle guards                              |
+| `cloud-finops-analyst`                       | 💰 FinOps leads, cost governance teams                                    |        9 | Cost optimization governors, anomaly watch, budget runaway guards, capacity planning — AWS · Azure · OCI                                  |
+| `cloud-solutions-architect`                  | 🏛️ Cloud architects, migration leads, AI/generative engineers             |       20 | Solution architecture, migration cutover, resilience/BCDR, event-driven design, multi-cloud, AI/generative — AWS · Azure · OCI            |
+| `cloud-devops-engineer`                      | 🚀 CI/CD engineers, release managers, SRE ops                             |       25 | CI/CD, pipeline approval gates, live rollout guards, deployment hotfix operators, serverless readiness, observability — AWS · Azure · OCI |
+| `kubernetes-admission-security-engineer`     | 🛡️ Platform security, policy engineers, admission control owners          |        6 | Kyverno policy review, K8s workload identity, PSA profiles, live admission-policy guard, live RBAC guard                                  |
+| `kubernetes-network-engineer`                | 🐝 Network engineers, platform SREs, zero-trust mesh owners               |        5 | Cilium/NetworkPolicy review, Istio ambient mesh review, live network-policy and mesh-policy guards                                        |
+| `kubernetes-application-platform-engineer`   | 🔄 Platform engineers, GitOps owners, ArgoCD operators                    |        3 | Argo CD GitOps review, live ArgoCD sync guard, kubernetes-maestro router                                                                  |
+| `kubernetes-runtime-security-engineer`       | 🔍 Runtime security, observability, and threat detection engineers        |        6 | Falco threat rules, Sigstore supply chain, K8s workload identity, RBAC review, pod-spec review, live RBAC guard                          |
+| `kubernetes-pki-engineer`                    | 🔐 PKI/cert lifecycle engineers, secrets management owners                |        6 | cert-manager Issuer/ClusterIssuer, CertificateRequestPolicy gap, ESO scope, AWS Private CA, Azure KV cert, OCI Certificates              |
+| `kubernetes-observability-engineer`          | 📊 SRE observability engineers, FinOps cost analysts                      |        4 | Prometheus alerting/cardinality, OTEL Collector pipeline, Kubecost chargeback/allocation, maestro router                                  |
+| `kubernetes-supply-chain-security-engineer`  | 🔏 Supply chain security engineers, DevSecOps practitioners               |        7 | Sigstore/Cosign, Falco runtime rules, Kyverno admission policy, PSA hardening, pod-spec review, live admission guard                      |
+| `kubernetes-developer-platform-engineer`     | 🎭 IDP/platform engineers, GitOps owners, developer experience leads      |        6 | Backstage Scaffolder templates, Argo CD, Argo Rollouts progressive delivery, FluxCD Kustomization/HelmRelease, maestro router             |
+| `kubernetes-disaster-recovery-engineer`      | 💾 SRE disaster recovery engineers, backup and restore owners             |        2 | Velero live-guarded restore operations with pre-restore checklist, maestro router                                                         |
+
+```bash
+# 🔍 See exactly which roles exist and how many agents each has
+npx vfa-export-agents --list-roles
+
+# 📦 Install a cloud role
+npx vfa-export-agents --platform claude-code --role cloud-security-engineer --repo .
+
+# ☁️  Install a cloud role but only for one provider
+npx vfa-export-agents --platform claude-code --role cloud-security-engineer --provider azure --repo .
+
+# ☸️  Install a Kubernetes specialist role
+npx vfa-export-agents --platform claude-code --role kubernetes-admission-security-engineer --repo .
+npx vfa-export-agents --platform claude-code --role kubernetes-network-engineer --repo .
+```
+
+---
+
+### ☁️ Provider reference
+
+Use `--provider` with `--role` to narrow the install to one cloud.
+
+| `--provider` value  | Domain                                   | 🔢 Agents in catalog |
+| ------------------- | ---------------------------------------- | ------------------: |
+| `aws`               | 🟧 Amazon Web Services                    |                  44 |
+| `azure`             | 🟦 Microsoft Azure                        |                  33 |
+| `oci`               | 🟥 Oracle Cloud Infrastructure            |                  36 |
+| `kubernetes`        | ☸️ Kubernetes (cross-cloud)               |                  13 |
+| `kyverno`           | 🛡️ Kyverno (admission policy)            |                   1 |
+| `argocd`            | 🔄 Argo CD + Argo Rollouts (GitOps)       |                   2 |
+| `istio`             | 🕸️ Istio (service mesh)                  |                   1 |
+| `cilium`            | 🐝 Cilium (network policy)                |                   1 |
+| `opentelemetry`     | 📡 OpenTelemetry (observability)          |                   1 |
+| `terraform`         | 🟩 Terraform (cross-cloud)                |                   2 |
+| `multi-cloud`       | 💰 FinOps / multi-cloud                   |                   1 |
+| `prometheus`        | 📊 Prometheus (alerting + cardinality)    |                   1 |
+| `falco`             | 🦅 Falco (runtime threat detection)       |                   1 |
+| `sigstore`          | 🔏 Sigstore / Cosign (supply chain)       |                   1 |
+| `cert-manager`      | 🔐 cert-manager (PKI / cert lifecycle)    |                   1 |
+| `fluxcd`            | 🔄 FluxCD (GitOps)                        |                   1 |
+| `backstage`         | 🎭 Backstage (IDP / developer platform)   |                   1 |
+| `velero`            | 💾 Velero (backup + restore)              |                   0 |
+
+```bash
+# 🟥 Install every OCI agent for a cloud-platform-engineer (OCI-only team)
+npx vfa-export-agents --platform codex --role cloud-platform-engineer --provider oci --repo .
+
+# 🟦 Install every Azure agent for a cloud-devops-engineer
+npx vfa-export-agents --platform copilot --role cloud-devops-engineer --provider azure --repo .
+```
+
+---
+
+### 🎯 Common install scenarios
+
+| 🙋 I want to…                                    | Command                                                                                                               |
+| ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| 🔍 See what agents exist                         | `npx vfa-export-agents --list`                                                                                        |
+| 🔍 See what roles exist                          | `npx vfa-export-agents --list-roles`                                                                                  |
+| 👤 Install for my job role (Claude Code)         | `npx vfa-export-agents --platform claude-code --role <role> --repo .`                                                 |
+| ☁️ Install for my job role, one cloud only       | `npx vfa-export-agents --platform claude-code --role <role> --provider aws --repo .`                                  |
+| ☸️ Install K8s admission security role           | `npx vfa-export-agents --platform claude-code --role kubernetes-admission-security-engineer --repo .`                 |
+| 🐝 Install K8s network engineering role          | `npx vfa-export-agents --platform claude-code --role kubernetes-network-engineer --repo .`                            |
+| 🧭 Install the Kubernetes maestro router only    | `npx vfa-export-agents --platform claude-code --agents kubernetes-maestro-agent --repo .`                             |
+| 🎯 Install one specific agent                    | `npx vfa-export-agents --platform claude-code --agents kubernetes-rbac-review-agent --repo .`                         |
+| 🎯 Install two specific agents                   | `npx vfa-export-agents --platform claude-code --agents agent-id-1,agent-id-2 --repo .`                                |
+| 💥 Install everything for Codex                  | `npx vfa-export-agents --platform codex --all --repo .`                                                               |
+| 🔄 Re-install and overwrite existing files       | `npx vfa-export-agents --platform claude-code --role <role> --repo . --force`                                         |
+| 📂 Install into a different repo path            | `npx vfa-export-agents --platform gemini --role <role> --repo /path/to/other-repo`                                    |
+| 🏭 Enforce via CI/CD pipeline                    | See [`docs/ci-cd-enforcement-pattern.md`](docs/ci-cd-enforcement-pattern.md)                                          |
 
 ---
 
@@ -123,8 +410,10 @@ QSAs, legal counsel, or official standards.
 It is a **control-aware engineering toolbox**. The assets should help teams
 design and collect evidence for common security expectations across frameworks.
 
-| Framework / standard              | What it pushes us to remember                                                                                                                                     | Repo design implication                                                                                   |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+Every live-guard and review agent produces a **structured verdict response** (`verdict`, `evidence_level`, `blockers`, `safe_next_actions`, `open_questions`) that maps directly to SOC 2 CC6.1, PCI DSS Req 7, NIS2 Article 21, NIST CSF PR.AC-4, and ISO 27001 A.9.1.1 — no post-processing required. See [`docs/evidence-output-spec.md`](docs/evidence-output-spec.md) for the full control mapping and evidence retention guidance.
+
+| Framework / standard             | What it pushes us to remember                                                                                                                                     | Repo design implication                                                                                   |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
 | 🔵 **SOC 2 Type 2**               | Controls must operate over a period of time, especially around security, availability, confidentiality, processing integrity, and privacy trust service criteria. | Workflows should leave evidence trails, not just one-time fixes.                                          |
 | 💳 **PCI DSS**                    | Cardholder data environments need scoped controls, secure configuration, access control, monitoring, vulnerability management, and testing.                       | Workflows should reduce scope, avoid broad access, and flag payment-data risk.                            |
 | 🇪🇺 **NIS2**                       | EU cybersecurity rules emphasize governance, risk management, incident reporting, supply-chain security, and management accountability.                           | Workflows should make ownership, reporting, and supplier/cloud dependencies explicit.                     |
@@ -132,7 +421,7 @@ design and collect evidence for common security expectations across frameworks.
 | 🏛️ **NIST SP 800-207 Zero Trust** | Access should be continuously evaluated and should not rely on implicit network trust.                                                                            | Agents and skills should challenge flat networks, permanent credentials, and unverified trust boundaries. |
 
 Ruthless correction: **NIS2** is the European cybersecurity directive. **NIST**
-is a U.S. standards body. If someone says “NIST2 European compliance,” they
+is a U.S. standards body. If someone says "NIST2 European compliance," they
 probably mean **NIS2** or they are mixing two different things.
 
 ---
@@ -141,8 +430,8 @@ probably mean **NIS2** or they are mixing two different things.
 
 Use these principles when creating or reviewing assets:
 
-| Principle                   | What good looks like                                                                  |
-| --------------------------- | ------------------------------------------------------------------------------------- |
+| Principle                  | What good looks like                                                                  |
+| -------------------------- | ------------------------------------------------------------------------------------- |
 | 👤 Identity-first           | Humans, workloads, agents, and CI/CD jobs have explicit identities.                   |
 | 🔐 Least privilege          | Permissions are narrow, justified, and reviewable.                                    |
 | 🧱 Segmented blast radius   | Network, account, project, subscription, tenancy, and data boundaries are deliberate. |
@@ -156,201 +445,17 @@ Use these principles when creating or reviewing assets:
 
 ## 🧭 Quick map
 
-| Folder                     | What lives here                                  | Easy memory hook                       |
-| -------------------------- | ------------------------------------------------ | -------------------------------------- |
-| [`skills/`](skills/)       | Reusable workflows grouped by provider or domain | 🧠 “How do I do this task?”            |
-| [`agents/`](agents/)       | Expert roles grouped by provider or domain       | 🤖 “Who should review this?”           |
-| [`rules/`](rules/)         | Harness-specific instructions                    | 📏 “What behavior is always expected?” |
-| [`mcp/`](mcp/)             | MCP server references and trust notes            | 🔌 “What can this connect to?”         |
-| [`catalog/`](catalog/)     | JSON indexes for marketplace discovery           | 🗂️ “What assets exist?”                |
-| [`schemas/`](schemas/)     | Metadata validation contracts                    | ✅ “What fields are required?”         |
-| [`templates/`](templates/) | Starter templates for new assets                 | 🧱 “How do I add one?”                 |
-| [`docs/`](docs/)           | Quality rules, taxonomy, and marketplace notes   | 📚 “How should this repo work?”        |
-| [`assets/`](assets/)       | Logos and visual assets                          | 🎨 “What images can docs use?”         |
-
----
-
-## 📦 Consumer install and export selected agents
-
-This repository is designed so consumers can install **selected marketplace
-agents** into their own project instead of copying everything by hand.
-
-### Current package status
-
-As of **2026-04-28**, the public npm package:
-
-```bash
-@raishin/vanguard-frontier-agentic
-```
-
-was verified as **not yet published** on npm.
-
-Live check:
-
-```bash
-npm view @raishin/vanguard-frontier-agentic version
-```
-
-If that command returns `404 Not Found`, the package is still unpublished.
-
-### Use it today from GitHub
-
-Until npm publishing is live, install from GitHub:
-
-```bash
-npm install github:Raishin/vanguard-frontier-agentic
-```
-
-### Export selected agents into a consumer repository
-
-After installation, this package ships a CLI:
-
-```bash
-vfa-export-agents
-```
-
-It copies selected agent harness files from this marketplace into the correct
-runtime folders in a consumer repository.
-
-List available agent IDs:
-
-```bash
-npx vfa-export-agents --list
-```
-
-Export one agent to **Claude Code**:
-
-```bash
-npx vfa-export-agents \
-  --platform claude-code \
-  --agents azure-cosmosdb-platform-operator-agent \
-  --repo /path/to/consumer-repo
-```
-
-Export one agent to **GitHub Copilot**:
-
-```bash
-npx vfa-export-agents \
-  --platform copilot \
-  --agents azure-cosmosdb-platform-operator-agent \
-  --repo /path/to/consumer-repo
-```
-
-Export one agent to **Kiro** (both IDE + CLI adapters):
-
-```bash
-npx vfa-export-agents \
-  --platform kiro \
-  --agents azure-cosmosdb-platform-operator-agent \
-  --repo /path/to/consumer-repo
-```
-
-Export **all** agents for a platform:
-
-```bash
-npx vfa-export-agents --platform codex --all --repo /path/to/consumer-repo
-```
-
-Overwrite existing exported files intentionally:
-
-```bash
-npx vfa-export-agents --platform copilot --all --repo /path/to/consumer-repo --force
-```
-
-### Platform destination folders
-
-The exporter writes into the destination repository using platform-native
-runtime paths:
-
-| Platform | Destination path(s) |
-| -------- | ------------------- |
-| Codex | `.codex/agents/` |
-| Claude Code | `.claude/agents/` |
-| GitHub Copilot | `.github/agents/` |
-| Cursor | `.cursor/agents/` |
-| Gemini CLI | `.gemini/agents/` |
-| Kiro IDE | `.kiro/agents/` |
-| Kiro CLI | `.kiro/agents/` |
-
-### Important limitation
-
-This exporter installs **custom agent files**, not full repo-level guidance.
-
-If the consumer also wants the repository-level instruction layer, they should
-use the matching project entrypoints in their own repo as appropriate:
-
-- `AGENTS.md`
-- `CLAUDE.md`
-- `GEMINI.md`
-- `.github/copilot-instructions.md`
-
-See [`docs/normalized-platform-matrix.md`](docs/normalized-platform-matrix.md)
-for the exact distinction between repo guidance and custom agent installation.
-
----
-
-## 🧠 Skills
-
-Skills are practical workflows. They should help an engineer complete a task
-with less guesswork.
-
-Current provider layout:
-
-```text
-skills/
-├── aws/
-├── azure/
-├── gcp/
-├── kubernetes/
-├── oci/
-├── security/
-└── terraform/
-```
-
-Examples:
-
-- 🔐 [`skills/aws/aws-iam-least-privilege-review`](skills/aws/aws-iam-least-privilege-review/)  
-  Review AWS IAM policies and reduce unnecessary access.
-
-- 🟦 [`skills/azure/azure-rbac-review`](skills/azure/azure-rbac-review/)  
-  Review Azure RBAC assignments, scopes, and custom roles.
-
-- 🟥 [`skills/oci/oci-autonomous-database-architect`](skills/oci/oci-autonomous-database-architect/)  
-  Design and review Oracle Autonomous Database across OCI and multicloud options.
-
-- 🏗️ [`skills/oci/oci-exadata-database-architect`](skills/oci/oci-exadata-database-architect/)  
-  Stress-test Exadata architecture, migration, HA/DR, and deployment choices.
-
-- 🔌 [`skills/oci/oracle-oci-mcp-grounded-advisor`](skills/oci/oracle-oci-mcp-grounded-advisor/)  
-  Ground Oracle/OCI MCP and cloud advice in official sources.
-
-Rule of thumb: if the asset teaches **how to do a repeatable task**, it is
-probably a skill.
-
----
-
-## 🤖 Agents
-
-Agents are reusable expert roles. They are organized by cloud provider or domain
-so engineers can find the right reviewer quickly.
-
-```text
-agents/
-├── aws/
-├── azure/
-├── gcp/
-├── oci/
-├── multi-cloud/
-├── security/
-└── terraform/
-```
-
-Example:
-
-- 🧱 [`agents/terraform/terraform-reviewer`](agents/terraform/terraform-reviewer/)  
-  Review Terraform modules, plans, provider usage, and state assumptions.
-
-Use an agent when you need a **role with judgment**, not just a checklist.
+| Folder                     | What lives here                                                               | Easy memory hook                      |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------------------------- |
+| [`skills/`](skills/)       | Reusable workflows grouped by provider or domain                              | 🧠 "How do I do this task?"            |
+| [`agents/`](agents/)       | Expert roles grouped by provider or domain                                    | 🤖 "Who should review this?"           |
+| [`rules/`](rules/)         | Harness-specific instructions                                                 | 📏 "What behavior is always expected?" |
+| [`mcp/`](mcp/)             | MCP server references and trust notes                                         | 🔌 "What can this connect to?"         |
+| [`catalog/`](catalog/)     | JSON indexes for marketplace discovery                                        | 🗂️ "What assets exist?"                |
+| [`schemas/`](schemas/)     | Metadata validation contracts                                                 | ✅ "What fields are required?"         |
+| [`templates/`](templates/) | Starter templates for new assets                                              | 🧱 "How do I add one?"                 |
+| [`docs/`](docs/)           | Quality rules, taxonomy, compliance evidence spec, CI/CD enforcement patterns | 📚 "How should this repo work?"        |
+| [`assets/`](assets/)       | Logos and visual assets                                                       | 🎨 "What images can docs use?"         |
 
 ---
 
@@ -369,29 +474,6 @@ production access, not like harmless documentation links.
 
 ---
 
-## 🎨 Logos and assets
-
-Visual assets are organized for future documentation, marketplace cards, and
-generated outputs.
-
-```text
-assets/logos/
-├── cloud/
-│   └── oci/
-└── vendors/
-    └── oracle/
-```
-
-Use:
-
-- `cloud/<provider>/` for platform or service logos.
-- `vendors/<vendor>/` for company/vendor logos.
-- SVG first, PNG fallback when needed.
-
-See [`assets/logos/README.md`](assets/logos/README.md).
-
----
-
 ## ✅ Quality bar
 
 This repo is **not** a prompt junk drawer.
@@ -402,13 +484,12 @@ Every cataloged asset should be:
 - 🔐 **Security-aware** — explains access, risk, and least-privilege concerns.
 - 🧪 **Validated** — passes repo checks before being shared.
 - 🧭 **Scoped** — clearly says which provider, domain, and harness it supports.
-- 🧯 **Safe by default** — read-only discovery before mutation; approval before
-  dangerous actions.
+- 🧯 **Safe by default** — read-only discovery before mutation; approval before dangerous actions.
 
 Hard no:
 
 - ❌ Secrets or credentials.
-- ❌ Vague “do everything” prompts.
+- ❌ Vague "do everything" prompts.
 - ❌ Unsafe production mutation recipes.
 - ❌ Cloud claims with no source or verification path.
 
@@ -436,35 +517,14 @@ Required common fields:
 - `last_verified`
 - `path`
 
-MCP references also need:
-
-- official project/source URL
-- vendor
-- auth model
-- install/config example
-- unofficial/community warning when relevant
-
 ---
 
 ## 🔏 Skill integrity manifests
 
 Skills are executable guidance. Treat them like supply-chain artifacts.
 
-This repo uses:
-
-```text
-catalog/skill-manifest.json
-```
-
-to record SHA-256 hashes for every file under every cataloged skill directory.
-
-Why it matters:
-
-- 🧾 proves what changed between releases,
-- 🚨 catches accidental or unauthorized edits,
-- 📦 gives npm consumers a package-level integrity map,
-- 🧪 makes skill integrity testable in CI,
-- 🔍 supports audit evidence for security-conscious teams.
+This repo uses `catalog/skill-manifest.json` to record SHA-256 hashes for every
+file under every cataloged skill directory.
 
 After intentional skill edits, regenerate the manifest:
 
@@ -478,9 +538,6 @@ Before release or review, check it:
 npm run manifest:check
 ```
 
-Ruthless truth: a manifest proves file integrity. It does **not** prove a skill
-is safe, correct, compliant, or officially endorsed. You still need review.
-
 ---
 
 ## 🧪 Validate your changes
@@ -499,13 +556,6 @@ python tests/validate-skill-manifest.py
 python tests/validate-links.py --offline
 ```
 
-Before a release, also run the online link check and npm package preview:
-
-```bash
-python tests/validate-links.py
-npm pack --dry-run
-```
-
 If validation fails, fix that first. A broken catalog makes the marketplace
 harder to trust.
 
@@ -513,23 +563,50 @@ harder to trust.
 
 ## 📦 npm publishing and semantic versioning
 
-This repository is npm-ready through [`package.json`](package.json).
-
 Use SemVer: `MAJOR.MINOR.PATCH`.
 
-| Version bump | Use when                                                                                                                                 | Example           |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
-| 🩹 `PATCH`   | Safe fixes: typos, metadata corrections, non-behavioral doc cleanup, manifest refresh after safe edits.                                  | `0.1.0` → `0.1.1` |
-| ✨ `MINOR`   | Backwards-compatible additions: new skills, new agents, new provider folders, new optional metadata.                                     | `0.1.0` → `0.2.0` |
-| 💥 `MAJOR`   | Breaking changes: removed/renamed IDs, moved paths without aliases, schema-required-field changes, incompatible manifest format changes. | `1.4.2` → `2.0.0` |
-
-While the package is below `1.0.0`, be extra explicit in release notes because
-minor bumps may still include early breaking design changes.
+| Version bump | Use when                                                  | Example           |
+| ------------ | --------------------------------------------------------- | ----------------- |
+| 🩹 `PATCH`    | Typos, metadata corrections, manifest refresh             | `0.1.0` → `0.1.1` |
+| ✨ `MINOR`    | New skills, agents, provider folders, optional metadata   | `0.1.0` → `0.2.0` |
+| 💥 `MAJOR`    | Removed/renamed IDs, moved paths, breaking schema changes | `1.4.2` → `2.0.0` |
 
 Read the full policy in [`docs/release-versioning.md`](docs/release-versioning.md).
 
 ---
 
+## 🧑‍💻 How to add a new asset
+
+1. 🧭 Pick the right folder — `skills/<provider>/`, `agents/<provider>/`, `rules/<harness>/`, or `mcp/official/`.
+2. 🧱 Start from a template — [`templates/skill-template`](templates/skill-template/) or [`templates/agent-template`](templates/agent-template/).
+3. 🗂️ Add or update catalog metadata in the matching `catalog/*.json` file.
+4. ✅ Run `npm run validate`.
+5. 🧯 Check safety — no secrets, no broad permissions without justification, no destructive actions without approval gates.
+
+---
+
+## ❓ FAQ
+
+**Skills vs agents — what's the difference?**<br>
+A **skill** teaches your coding agent *how to do a task* (step-by-step workflow, CLI commands, reference material). An **agent** gives your coding agent a *role with judgment* — it loads the skill and adds a guarded response shape, approval gates, and a hardened permission model.
+
+**Do I need a cloud account to use these?**<br>
+For reviewing architecture, writing IaC, or planning — no. For live-guard agents that execute against a real environment — yes, and they will ask you to confirm subscription/tenancy/principal before any mutation.
+
+**Can I use a skill or agent without the exporter CLI?**<br>
+Yes. Copy the harness file for your platform from `agents/<provider>/<id>/harnesses/` directly into your repo's agent folder. The CLI just automates that copy.
+
+**What is a "live guard" agent?**<br>
+A live-guard agent operates against a real cloud environment. It enforces approval gates before any mutation, requires preflight evidence (what-if/plan/status output), and treats missing rollback design as a stop condition. Live guards are refusal-by-default — if target identity, approval state, or rollback posture is ambiguous, they stop and say so.
+
+**What does the FinOps price advisor actually do?**<br>
+It fetches live on-demand prices from AWS Price List API, Azure Retail Prices API, and OCI public pricing API — all public, unauthenticated endpoints. It never needs billing credentials. Currency defaults to USD; other currencies are available via Azure's native `currencyCode` parameter or public exchange rate APIs for AWS/OCI.
+
+**Can I contribute new skills or agents?**<br>
+Yes — see [Contributing](#contributing). The baseline requirement: the asset must be specific, source-backed, security-aware, and validated by `npm run validate`.
+
+---
+
 ## 📚 Source anchors
 
 Use official sources when writing security or compliance-sensitive assets:
@@ -541,52 +618,25 @@ Use official sources when writing security or compliance-sensitive assets:
 - 💳 [PCI Security Standards Council Document Library](https://www.pcisecuritystandards.org/document_library)
 - 🔵 [AICPA SOC 2 Trust Services Criteria](https://www.aicpa-cima.com/topic/audit-assurance/audit-and-assurance-greater-than-soc-2)
 
-Prefer these over blog posts. Blog posts can help explain, but they are not the
-source of truth.
+Prefer these over blog posts. Blog posts can help explain, but they are not the source of truth.
 
 ---
 
-## 🧑‍💻 How to add a new asset
+## 💬 Feedback
 
-1. 🧭 Pick the right folder.
-   - Cloud workflow? Put it under `skills/<provider>/`.
-   - Expert role? Put it under `agents/<provider-or-domain>/`.
-   - Harness instruction? Put it under `rules/<harness>/`.
-   - MCP info? Put it under `mcp/official/` or `mcp/community/`.
+We value your input — it helps improve this marketplace for the whole community.
 
-2. 🧱 Start from a template.
-   - Use [`templates/skill-template`](templates/skill-template/) for skills.
-   - Use [`templates/agent-template`](templates/agent-template/) for agents.
-
-3. 🗂️ Add or update catalog metadata.
-   - Skills go in [`catalog/skills.json`](catalog/skills.json).
-   - Agents go in [`catalog/agents.json`](catalog/agents.json).
-   - Rules go in [`catalog/rules.json`](catalog/rules.json).
-   - MCP references go in [`catalog/mcp-references.json`](catalog/mcp-references.json).
-
-4. ✅ Run validation.
-
-5. 🧯 Check safety.
-   - No secrets.
-   - No broad permissions unless justified.
-   - No destructive actions without approval gates and rollback notes.
+- **Bugs & feature requests:** [open an issue](https://github.com/Raishin/vanguard-frontier-agentic/issues/new) — 👍 the ones you want prioritized.
+- **New skill or agent ideas:** describe the use case in an issue and we will review.
+- **Security concerns:** see [`SECURITY.md`](SECURITY.md) for responsible disclosure.
 
 ---
 
-## 🛡️ Contribution stance
+## 🛡️ Contributing
 
-The default answer to low-trust contributions is **no**.
+The default answer to low-trust contributions is **no**. That is intentional — cloud automation can break real systems.
 
-That is intentional. Cloud automation can break real systems.
-
-Good contributions are:
-
-- useful,
-- specific,
-- auditable,
-- source-backed,
-- safe by default,
-- friendly for engineers of any seniority.
+Good contributions are: useful, specific, auditable, source-backed, safe by default, and friendly for engineers of any seniority.
 
 See:
 
@@ -598,13 +648,10 @@ See:
 
 ---
 
-## 🧠 Remember this
-
 ```text
-Skills = workflows 🧠
-Agents = expert roles 🤖
-Rules = always-on behavior 📏
-MCP = real tool connections 🔌
-Catalog = searchable index 🗂️
-Validation = trust ✅
+Skills  = workflows        🧠   138 across AWS · Azure · OCI · Kubernetes · CNCF · Terraform
+Agents  = expert roles     🤖   141 with 7 harness adapters each
+Rules   = always-on        📏   harness-specific operating guidance
+MCP     = real connections 🔌   AWS · Azure · Oracle official servers
+Catalog = searchable index 🗂️   machine-readable, hash-verified
 ```