diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..824b549
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,41 @@
+---
+name: Bug report
+about: Report a reproducible OpenGhost bug
+title: "bug: "
+labels: bug
+assignees: ""
+---
+
+## Summary
+
+Describe the bug and the expected behavior.
+
+## Environment
+
+- OS:
+- Shell:
+- Docker version:
+- OpenGhost commit:
+- Sandbox image digest, if relevant:
+
+## Steps to Reproduce
+
+1.
+2.
+3.
+
+## Actual Result
+
+Paste the relevant non-sensitive output.
+
+## Expected Result
+
+Describe what should have happened.
+
+## Validation
+
+List any commands already run.
+
+## Safety Check
+
+- [ ] This report does not include real target data, credentials, tokens, traffic captures, or private vulnerability evidence.
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..d5b072a
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/VAIBHAVSING/openghost/security
+    about: Report vulnerabilities privately. Do not open public issues with exploit details.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..edd2d3b
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,23 @@
+---
+name: Feature request
+about: Propose an OpenGhost improvement
+title: "feat: "
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What operator workflow, skill behavior, or sandbox capability is missing?
+
+## Proposal
+
+Describe the change.
+
+## Alternatives
+
+List any current workaround.
+
+## Safety and Scope
+
+Explain how this keeps authorization, Docker-only execution, and evidence quality intact.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..2c9a61a
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,16 @@
+## Summary
+
+-
+
+## Validation
+
+- [ ] `bash -n openghost skills/openghost skills/openghost-skill/openghost skills/openghost-skill/scripts/openghost.sh skills/openghost-skill/scripts/verify-toolchain.sh`
+- [ ] `python3 -m py_compile skills/openghost-skill/scripts/select-modules.py skills/openghost-skill/scripts/openghost-state.py`
+- [ ] Skill validation, if `skills/openghost-skill` changed
+- [ ] Docker/toolchain validation, if `docker/` changed
+
+## Security and Safety
+
+- [ ] No credentials, target data, traffic captures, or real assessment evidence are included.
+- [ ] Security tooling still runs through `openghost`.
+- [ ] Documentation was updated for changed commands, paths, or behavior.
diff --git a/.github/workflows/publish-sandbox-image.yml b/.github/workflows/publish-sandbox-image.yml
index a5462dd..17b65f4 100644
--- a/.github/workflows/publish-sandbox-image.yml
+++ b/.github/workflows/publish-sandbox-image.yml
@@ -9,11 +9,11 @@ on:
       - "v*"
     paths:
       - ".github/workflows/publish-sandbox-image.yml"
-      - "developer/docker/**"
+      - "docker/**"
   pull_request:
     paths:
       - ".github/workflows/publish-sandbox-image.yml"
-      - "developer/docker/**"
+      - "docker/**"
 
 permissions:
   contents: read
@@ -75,13 +75,13 @@ jobs:
             org.opencontainers.image.title=OpenGhost sandbox
             org.opencontainers.image.description=Developer sandbox image for the OpenGhost skill
             org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
-            org.opencontainers.image.licenses=MIT
+            org.opencontainers.image.licenses=Apache-2.0
 
       - name: Build and push
         uses: docker/build-push-action@v6
         with:
-          context: developer/docker
-          file: developer/docker/Dockerfile
+          context: docker
+          file: docker/Dockerfile
           platforms: linux/amd64,linux/arm64
           push: ${{ github.event_name != 'pull_request' }}
           tags: ${{ steps.meta.outputs.tags }}
diff --git a/.gitignore b/.gitignore
index 4c3cb96..6a2810b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,5 @@
 .agents/*
 !.agents/.gitkeep
+
+__pycache__/
+*.py[cod]
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1525c77
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,164 @@
+# AGENTS.md
+
+Project context for coding agents working on OpenGhost.
+
+## What This Repo Is
+
+OpenGhost is an original standalone Agent Skill for authorized web application and server integrity penetration testing. The repo packages skill instructions, reference methodology, evidence/reporting helpers, and a Docker-backed launcher that keeps security tooling out of the host environment.
+
+The central design constraint is simple: agents provide reasoning and workflow control, while OpenGhost provides the sandboxed execution layer and structured engagement state.
+
+## Product Boundary
+
+- This repository owns the OpenGhost skill package and sandbox launcher.
+- Security tools must be executed through `openghost`, not directly on the host.
+- External research/reference directories are not runtime dependencies and should not be cited as OpenGhost source material.
+- Generated engagement data belongs under `.openghost/` and should normally stay uncommitted.
+
+## Agent Skill Structure
+
+OpenGhost follows the standard Agent Skill layout:
+
+- `skills/openghost-skill/SKILL.md` is the published skill entrypoint and operator workflow.
+- Keep `SKILL.md` focused and use progressive disclosure: short entrypoint instructions first, deeper details in references.
+- `skills/openghost-skill/references/` contains deeper guidance that agents should load only when relevant.
+- `skills/openghost-skill/scripts/` contains deterministic helpers and launcher implementation.
+- `skills/openghost-skill/assets/` contains templates and reusable output files.
+- Do not duplicate large methodology content across files; link to the canonical reference instead.
+
+## Main Source Paths
+
+- `skills/openghost-skill/SKILL.md` - published skill entrypoint and operator workflow.
+- `skills/openghost-skill/references/` - deeper guidance for modules, reporting, tooling, auth, and workflow.
+- `skills/openghost-skill/references/modules/` - assessment modules such as surface mapping, session auth, access control, injection, APIs, browser policy, HTTP edge, business logic, and server integrity.
+- `skills/openghost-skill/scripts/openghost.sh` - canonical CLI and Docker sandbox implementation.
+- `skills/openghost-skill/scripts/verify-toolchain.sh` - runtime toolchain verification.
+- `skills/openghost-skill/scripts/select-modules.py` - module selection helper.
+- `skills/openghost-skill/assets/` - templates for scope, auth, findings, and reports.
+- `skills/openghost-skill/agents/` - compatibility notes for other coding agents.
+
+## Launchers
+
+There are three launcher entrypoints:
+
+- `./openghost` forwards to `skills/openghost`.
+- `skills/openghost` forwards to `skills/openghost-skill/scripts/openghost.sh`.
+- `skills/openghost-skill/openghost` is the standalone fallback for installs that copy only the skill package.
+
+Keep launcher behavior consistent when changing CLI commands.
+
+## Sandbox Model
+
+The root `Dockerfile` intentionally delegates to `ghcr.io/vaibhavsing/openghost-sandbox:latest`. The actual maintainer image source is `docker/Dockerfile`.
+
+Normal users should pull the published image. Maintainers can set `OPENGHOST_BUILD=1` to build from `docker/`.
+
+The sandbox mounts the current workspace at `/workspace`, runs with dropped capabilities plus the minimum network capabilities needed for testing, and exposes tools through an allowlist in `openghost.sh`.
+
+## CLI Surface
+
+Primary commands:
+
+```bash
+./openghost sandbox start
+./openghost sandbox status
+./openghost sandbox stop
+./openghost sandbox update
+./openghost run <tool> [args...]
+./openghost bash '<command>'
+./openghost python code '<script>'
+./openghost python file <path> -- [args...]
+./openghost engagement init --url <target> --name <name>
+./openghost finding add ...
+./openghost finding list
+./openghost todo add ...
+./openghost todo list
+./openghost todo update ...
+./openghost report generate
+```
+
+Compatibility aliases exist in `openghost.sh`; preserve them unless intentionally making a breaking change.
+
+## Engagement State
+
+`openghost engagement init` creates:
+
+- `.openghost/config.json`
+- `.openghost/current`
+- `.openghost/engagements/<name>/scope.yaml`
+- `.openghost/engagements/<name>/engagement.json`
+- `.openghost/engagements/<name>/findings.json`
+- `.openghost/engagements/<name>/todos.json`
+- evidence, notes, reports, artifacts, scripts, browser, and run directories.
+
+`OPENGHOST_SCOPE` should point to the active `scope.yaml` before testing. Scope files are operational data, not source docs.
+
+## Safety Rules
+
+- Keep the authorization-first language in `SKILL.md`.
+- Do not weaken the Docker-only rule for security tools.
+- Do not remove the tool allowlist or bash blocklist casually.
+- Avoid adding commands that can modify or damage host state.
+- Keep examples scoped and non-destructive.
+- Finding/report helpers must distinguish confirmed evidence from speculation.
+
+## When Editing Tooling
+
+If adding a sandbox tool, check all relevant surfaces:
+
+- Install it in `docker/Dockerfile`.
+- Add it to `ALLOWED_TOOLS` in `skills/openghost-skill/scripts/openghost.sh` if agents should run it directly.
+- Add it to `skills/openghost-skill/scripts/verify-toolchain.sh` if it is required.
+- Add docs only where operators need to see it: usually `SKILL.md`, `references/tooling.md`, or a module file.
+- Keep root `Dockerfile` as a published-image delegate.
+
+If changing CLI behavior, update examples in `README.md`, `SKILL.md`, and any affected reference docs.
+
+## Documentation Style
+
+- `README.md` should stay minimal: purpose, repo contents, quick start, and requirements.
+- Detailed pentest methodology belongs in `SKILL.md` and `references/`.
+- Agent-facing maintenance context belongs here.
+- Keep docs direct and concise; avoid marketing copy.
+- Use ASCII unless the edited file already requires otherwise.
+
+## Verification
+
+For docs-only edits:
+
+```bash
+rg -n "old command|wrong path" README.md AGENTS.md skills/openghost-skill
+```
+
+For shell edits:
+
+```bash
+bash -n openghost
+bash -n skills/openghost
+bash -n skills/openghost-skill/openghost
+bash -n skills/openghost-skill/scripts/openghost.sh
+bash -n skills/openghost-skill/scripts/verify-toolchain.sh
+```
+
+For Python edits:
+
+```bash
+python3 -m py_compile skills/openghost-skill/scripts/select-modules.py
+```
+
+For sandbox/runtime changes:
+
+```bash
+./openghost sandbox status
+./skills/openghost-skill/scripts/verify-toolchain.sh
+```
+
+Only run Docker-heavy checks when Docker is available and the task requires runtime validation.
+
+## Common Pitfalls
+
+- Do not edit generated `.openghost/` engagement output as if it were source.
+- Do not put long operator instructions in `README.md`.
+- Do not duplicate the canonical CLI in another script; route through `openghost.sh`.
+- Do not make the root `Dockerfile` the maintainer image source.
+- Do not assume a reference directory in the workspace is part of the OpenGhost package.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..23b3e77
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,208 @@
+# Architecture
+
+OpenGhost separates agent reasoning from security tool execution.
+
+The agent owns planning, scope decisions, module selection, and reporting
+judgment. OpenGhost owns the sandboxed execution layer, deterministic helpers,
+engagement state, and evidence/report files.
+
+## Design Goals
+
+- Keep offensive tooling out of the host environment.
+- Make authorization, scope, and evidence explicit.
+- Give agents a short skill entrypoint with deeper references loaded only when
+  relevant.
+- Keep engagement output separate from source code.
+- Preserve one canonical launcher implementation.
+
+## System Overview
+
+```text
+Agent client
+  |
+  | reads
+  v
+skills/openghost-skill/SKILL.md
+  |
+  | calls
+  v
+openghost launcher
+  |
+  | starts / execs
+  v
+Docker sandbox
+  |
+  | writes structured state
+  v
+.openghost/engagements/<name>/
+```
+
+## Main Components
+
+### Skill Package
+
+`skills/openghost-skill/` is the published Agent Skill package.
+
+- `SKILL.md` is the entrypoint, metadata, safety rules, setup, and high-level
+  workflow.
+- `references/` contains deeper methodology for scope, workflow, tooling,
+  authentication, ZAP/Playwright, reporting, risk triage, threat modeling, and
+  modules.
+- `references/modules/` contains focused assessment modules such as surface
+  mapping, session auth, access control, injection, APIs, browser policy, HTTP
+  edge cases, business logic, and server integrity.
+- `scripts/` contains the launcher, state helper, verification helper, and
+  reusable pentest templates.
+- `assets/` contains reusable templates for scope, auth, findings, and reports.
+- `agents/` contains compatibility notes for specific agent clients.
+
+### Launchers
+
+OpenGhost has three entrypoints:
+
+- `./openghost` - repository root convenience wrapper.
+- `skills/openghost` - skill-local CLI shim.
+- `skills/openghost-skill/openghost` - standalone fallback for installs that
+  copy only the skill package.
+
+All entrypoints forward to:
+
+```text
+skills/openghost-skill/scripts/openghost.sh
+```
+
+Keep command behavior consistent across all entrypoints by changing
+`openghost.sh`, not by duplicating logic in wrappers.
+
+### Docker Sandbox
+
+The default runtime image is:
+
+```text
+ghcr.io/vaibhavsing/openghost-sandbox:latest
+```
+
+The root `Dockerfile` intentionally delegates to that published image so normal
+root builds behave like normal skill installs.
+
+Maintainers build the sandbox image from:
+
+```text
+docker/Dockerfile
+```
+
+The sandbox mounts the current workspace at `/workspace`, starts from
+`WORKDIR /workspace`, and exposes tools only through the launcher allowlist.
+The launcher also contains a bash blocklist for obvious destructive host or
+system-damage patterns.
+
+### State Helper
+
+`skills/openghost-skill/scripts/openghost-state.py` owns structured engagement
+state. The shell launcher delegates evidence, artifact, finding, todo, and
+report operations to this helper.
+
+Generated state normally lives under:
+
+```text
+.openghost/
+|-- config.json
+|-- current
+`-- engagements/
+    `-- <name>/
+        |-- scope.yaml
+        |-- engagement.json
+        |-- state/
+        |-- evidence/
+        |-- artifacts/
+        |-- scripts/
+        |-- notes/
+        |-- reports/
+        `-- runs/
+```
+
+`.openghost/` is operational data. It should normally stay uncommitted.
+
+## Command Flow
+
+### Sandbox Lifecycle
+
+```text
+openghost sandbox start
+  -> require Docker
+  -> pull or build image
+  -> start container
+  -> mount workspace
+```
+
+`OPENGHOST_BUILD=1` switches maintainer mode on and builds the local
+`docker/Dockerfile` instead of pulling the published image.
+
+### Tool Execution
+
+```text
+openghost run nmap ...
+  -> verify nmap is allowlisted
+  -> ensure sandbox exists
+  -> docker exec nmap ...
+```
+
+`openghost bash` and `openghost python` also run inside Docker. They are for
+assessment automation and parsing, not for bypassing scope or safety controls.
+
+### Script Templates
+
+```text
+openghost script run api-inventory -- --target-url https://target.example
+  -> read manifest
+  -> locate bundled script
+  -> execute inside Docker
+```
+
+Use `openghost script copy <name>` when a template needs target-specific
+changes. Modified copies belong under the active engagement's `scripts/`
+directory.
+
+### Evidence and Reporting
+
+```text
+openghost evidence add ...
+openghost finding add ...
+openghost report generate
+```
+
+Findings should reference evidence IDs and distinguish confirmed behavior from
+likely or possible signals.
+
+## Trust Boundaries
+
+- Host system: should not run offensive tools directly.
+- Docker sandbox: runs assessment tooling with workspace mount and constrained
+  capabilities.
+- Target system: must be explicitly authorized and represented in
+  `OPENGHOST_SCOPE`.
+- Engagement state: may contain sensitive operational data and evidence.
+- Source tree: should contain reusable skill/package code, not real target data.
+
+## Change Guide
+
+When changing the CLI:
+
+- Update `skills/openghost-skill/scripts/openghost.sh`.
+- Preserve compatibility aliases unless the breaking change is intentional.
+- Update `README.md`, `DEVELOPMENT.md`, and relevant skill references.
+- Run shell validation.
+
+When adding a sandbox tool:
+
+- Install it in `docker/Dockerfile`.
+- Add it to `ALLOWED_TOOLS` in `openghost.sh` when direct agent access is
+  intended.
+- Add it to `verify-toolchain.sh` if it is required.
+- Document operator usage only where operators need it.
+
+When adding assessment methodology:
+
+- Keep `SKILL.md` short.
+- Put detailed guidance in `references/` or `references/modules/`.
+- Avoid duplicating large methodology across files.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..d7c83c3
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,27 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to a respectful, harassment-free project environment for everyone.
+
+## Expected Behavior
+
+- Be direct, constructive, and respectful.
+- Keep disagreement focused on technical facts and project goals.
+- Respect authorized-testing boundaries and do not encourage misuse.
+- Avoid publishing sensitive target data, credentials, private reports, or exploit details in public discussions.
+
+## Unacceptable Behavior
+
+- Harassment, threats, personal attacks, or discriminatory language.
+- Encouraging unauthorized access, destructive testing, or abuse of third-party systems.
+- Sharing private vulnerability details, credentials, or customer data in public channels.
+- Repeatedly disrupting project discussions after maintainer direction.
+
+## Enforcement
+
+Maintainers may remove comments, close issues, block users, or restrict participation when behavior harms the project or its users. Security-sensitive material may be removed without prior discussion to reduce exposure.
+
+## Reporting
+
+Report conduct issues to the maintainers through a private GitHub contact path when possible. For vulnerabilities, use `SECURITY.md` instead of this code of conduct.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..6d62f58
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,35 @@
+# Contributing
+
+OpenGhost is an Agent Skill and Docker sandbox launcher for authorized security
+testing. Contributions should preserve the authorization-first workflow,
+Docker-only tool execution, and evidence quality gates.
+
+Start with:
+
+- [Architecture](ARCHITECTURE.md) for components and trust boundaries.
+- [Development](DEVELOPMENT.md) for setup, validation, and maintainer workflows.
+- [Security](SECURITY.md) for vulnerability reporting.
+
+## Contribution Rules
+
+- Keep generated engagement data under `.openghost/` and out of commits.
+- Do not commit credentials, target data, screenshots with sensitive data,
+  traffic captures, or real assessment evidence.
+- Run security tools through `openghost`, not directly on the host.
+- Keep `skills/openghost-skill/SKILL.md` focused and put detailed methodology in
+  `references/`.
+- Preserve launcher compatibility aliases unless a breaking change is intentional
+  and documented.
+- Keep the root `Dockerfile` as a delegate to the published sandbox image.
+
+## Pull Requests
+
+Pull requests should include:
+
+- What changed and why.
+- Validation commands run.
+- Any security, compatibility, or operator workflow impact.
+- Documentation updates for changed commands, paths, or behavior.
+
+Before opening a PR, check that no real target names, credentials, traffic
+captures, or vulnerability evidence from live systems are included.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..beba0c3
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,143 @@
+# Development
+
+This guide is for maintainers changing the OpenGhost skill package, launcher,
+sandbox image, or documentation.
+
+## Local Setup
+
+```bash
+git clone https://github.com/VAIBHAVSING/openghost.git
+cd openghost
+export PATH="$PWD/skills:$PWD/skills/openghost-skill:$PATH"
+openghost help
+```
+
+Docker is required for runtime testing. Documentation, shell syntax checks, and
+Python compilation checks can run without Docker.
+
+## Validation Commands
+
+Documentation-only changes:
+
+```bash
+rg -n "old command|wrong path" README.md ARCHITECTURE.md DEVELOPMENT.md CONTRIBUTING.md AGENTS.md skills/openghost-skill
+```
+
+Shell changes:
+
+```bash
+bash -n openghost
+bash -n skills/openghost
+bash -n skills/openghost-skill/openghost
+bash -n skills/openghost-skill/scripts/openghost.sh
+bash -n skills/openghost-skill/scripts/verify-toolchain.sh
+```
+
+Python changes:
+
+```bash
+PYTHONPYCACHEPREFIX=/tmp/openghost-pycache python3 -m py_compile \
+  skills/openghost-skill/scripts/select-modules.py \
+  skills/openghost-skill/scripts/openghost-state.py
+rm -rf /tmp/openghost-pycache
+```
+
+Skill package validation:
+
+```bash
+python3 /home/vsing/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/openghost-skill
+```
+
+Sandbox/runtime changes:
+
+```bash
+./openghost sandbox status
+./skills/openghost-skill/scripts/verify-toolchain.sh
+```
+
+Only run Docker-heavy checks when Docker is available and the change requires
+runtime validation.
+
+## Common Workflows
+
+### Update Skill Instructions
+
+1. Keep `skills/openghost-skill/SKILL.md` focused on routing, operating rules,
+   setup, and workflow.
+2. Put detailed methodology in `skills/openghost-skill/references/`.
+3. Put module-specific methodology in `skills/openghost-skill/references/modules/`.
+4. Keep examples scoped, authorized, and non-destructive by default.
+5. Run skill validation when the package structure or frontmatter changes.
+
+### Change CLI Behavior
+
+1. Change `skills/openghost-skill/scripts/openghost.sh`.
+2. Keep `./openghost`, `skills/openghost`, and
+   `skills/openghost-skill/openghost` as wrappers.
+3. Preserve compatibility aliases unless intentionally breaking them.
+4. Update README examples and relevant references.
+5. Run shell validation.
+
+### Add A Sandbox Tool
+
+1. Install the tool in `docker/Dockerfile`.
+2. Add it to `ALLOWED_TOOLS` in `skills/openghost-skill/scripts/openghost.sh`
+   if agents should run it directly.
+3. Add it to `skills/openghost-skill/scripts/verify-toolchain.sh` if it is
+   required.
+4. Document usage in `SKILL.md`, `references/tooling.md`, or the relevant module.
+5. Keep the root `Dockerfile` as a delegate to the published image.
+
+Build a local developer image when needed:
+
+```bash
+OPENGHOST_BUILD=1 OPENGHOST_IMAGE=openghost-sandbox:dev ./openghost sandbox update
+```
+
+### Add A Script Template
+
+1. Add the script under `skills/openghost-skill/scripts/pentest/`.
+2. Give it safe defaults and a useful `--help`.
+3. Add metadata to `skills/openghost-skill/scripts/pentest/manifest.json`.
+4. Run it through `openghost script run` or `openghost python file`.
+5. Treat output as evidence to validate, not as an automatically confirmed
+   finding.
+
+### Add Or Update A Module
+
+1. Add module guidance under `skills/openghost-skill/references/modules/`.
+2. Keep the module focused on one assessment area.
+3. Link it from `SKILL.md` only where agents need to discover it.
+4. Update `skills/openghost-skill/references/module-map.md` when module
+   selection changes.
+5. Update `skills/openghost-skill/scripts/select-modules.py` when automatic
+   selection should include the module.
+
+## Skills.sh Listing
+
+This repository includes `skills.sh.json` at the root to improve how the repo is
+grouped on skills.sh.
+
+For compatibility:
+
+- Keep `skills/openghost-skill/SKILL.md` frontmatter valid.
+- Keep the `description` explicit about when agents should use the skill.
+- Keep references relative to the skill root.
+- Avoid duplicating long methodology in `README.md`.
+- Use the install form:
+
+```bash
+npx skills@latest add VAIBHAVSING/openghost --skill openghost-skill
+```
+
+## Release Checklist
+
+Before shipping:
+
+- [ ] README examples still match `openghost help`.
+- [ ] `ARCHITECTURE.md` still matches launcher, state, and Docker behavior.
+- [ ] `CONTRIBUTING.md` and `.github/PULL_REQUEST_TEMPLATE.md` validation lists
+      are still accurate.
+- [ ] No generated `.openghost/` data, credentials, target names, screenshots, or
+      traffic captures are staged.
+- [ ] Docker-heavy checks were run when runtime behavior changed.
diff --git a/Dockerfile b/Dockerfile
index b99fa4e..431e3f8 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,5 +1,5 @@
-# Developer sandbox Dockerfile lives at:
-# developer/docker/Dockerfile
+# Maintainer sandbox Dockerfile lives at:
+# docker/Dockerfile
 #
 # The root Dockerfile intentionally delegates to the published sandbox image so
 # accidental root builds behave like normal skill installs.
diff --git a/README.md b/README.md
index d413d06..0449b60 100644
--- a/README.md
+++ b/README.md
@@ -1,63 +1,81 @@
 # OpenGhost
 
+[![skills.sh](https://skills.sh/b/VAIBHAVSING/openghost)](https://skills.sh/VAIBHAVSING/openghost)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-SKILL.md-111827.svg)](https://agentskills.io/)
+[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-SKILL.md-111827.svg)](skills/openghost-skill/SKILL.md)
 
-OpenGhost is a standalone Agent Skill for authorized web application and server integrity penetration testing. It packages the operator workflow, module references, evidence helpers, report templates, and a Docker-backed launcher so AI agents can run structured assessments without installing security tools on the host.
+Agent Skill for authorized web application and server integrity penetration testing.
 
-The model is intentionally split:
-
-- The agent provides reasoning, planning, and workflow control.
-- OpenGhost provides the sandboxed execution layer, scope state, evidence records, and report output.
+OpenGhost gives AI coding agents a real assessment workflow: scoped targets,
+Docker-backed tool execution, evidence records, reusable checks, and report
+output. The agent reasons and coordinates; OpenGhost keeps security tools inside
+a sandbox and keeps engagement data organized under `.openghost/`.
 
 Use OpenGhost only on systems you are explicitly authorized to test.
 
-## Features
+## Quickstart
 
-- Agent Skill package with a `SKILL.md` entrypoint, reference docs, scripts, and assets.
-- Docker sandbox for security tooling, with an allowlist and host isolation.
-- Engagement state under `.openghost/`, including scope, evidence, artifacts, todos, findings, and reports.
-- Coverage for OWASP WSTG, OWASP API Top 10, pre-engagement planning, threat modeling, authenticated testing, access control, injection, browser policy, HTTP edge cases, business logic, server integrity, and risk triage.
-- Bundled low-impact Python templates for repeatable checks such as API inventory, web baseline, CORS, JWT, GraphQL, WebSocket, HPP, cache behavior, BOLA/BFLA, SQLi/NoSQLi probes, XSS reflection, and vulnerability triage.
-- ZAP, Playwright/browser validation, and common web assessment tools exposed through the `openghost` launcher.
+1. Install the skill:
 
-## Install
+   ```bash
+   npx skills@latest add VAIBHAVSING/openghost --skill openghost-skill
+   ```
 
-### Install as an Agent Skill
+2. Make sure Docker is running.
 
-If your agent supports the `skills` CLI, install the skill from GitHub:
+3. Ask your agent to use OpenGhost for an authorized assessment, or clone the repo
+   for direct CLI use:
 
-```bash
-npx skills add VAIBHAVSING/openghost --skill openghost-skill
-```
+   ```bash
+   git clone https://github.com/VAIBHAVSING/openghost.git
+   cd openghost
+   export PATH="$PWD/skills:$PWD/skills/openghost-skill:$PATH"
+   openghost help
+   ```
 
-The skill will become available to compatible agents through its `SKILL.md` metadata. The launcher still requires Docker at runtime.
+4. Start a scoped engagement:
 
-### Clone for local development or direct CLI use
+   ```bash
+   openghost sandbox start
+   openghost engagement init --url https://target.example --name target-example
+   export OPENGHOST_SCOPE=.openghost/engagements/target-example/scope.yaml
+   ```
 
-```bash
-git clone https://github.com/VAIBHAVSING/openghost.git
-cd openghost
-export PATH="$PWD/skills:$PWD/skills/openghost-skill:$PATH"
-```
+5. Edit the generated scope file before testing. Add allowed hosts, exclusions,
+   credentials, rate limits, test windows, emergency contacts, and rules of
+   engagement.
 
-Requirements:
+## Why OpenGhost Exists
 
-- Bash
-- Docker with a reachable daemon
-- Network access to pull `ghcr.io/vaibhavsing/openghost-sandbox:latest`
+### Security tools should not leak onto the host
 
-## Quick Start
+Agents are good at reasoning, but ad hoc host commands make security work messy.
+OpenGhost routes assessment tooling through `openghost`, which runs allowlisted
+commands inside a Docker sandbox.
 
-```bash
-openghost sandbox start
-openghost engagement init --url https://target.example --name target-example
-export OPENGHOST_SCOPE=.openghost/engagements/target-example/scope.yaml
-```
+### Pentests need scope discipline
+
+A useful assessment starts with explicit authorization, hosts, accounts, testing
+windows, rate limits, and exclusions. OpenGhost keeps those constraints in
+`OPENGHOST_SCOPE` and makes scope part of the operator workflow.
 
-Edit the generated scope file before testing. Add allowed hosts, excluded hosts and paths, credentials, rate limits, testing windows, emergency stop contacts, data-handling rules, cleanup expectations, and any rules of engagement.
+### Scanner output is not a finding
 
-Run non-destructive checks through the sandbox:
+OpenGhost treats scanners and scripts as leads. Findings should include evidence,
+reproduction steps, impact, confidence, priority, and remediation before they are
+reported as confirmed.
+
+### Agents need reusable structure
+
+The skill package gives agents a short `SKILL.md` entrypoint plus deeper module
+references only when needed. That keeps the main prompt readable while still
+covering OWASP WSTG, OWASP API Top 10, authenticated testing, access control,
+injection, browser policy, HTTP edge cases, business logic, server integrity,
+ZAP-backed DAST, and Playwright/browser validation.
+
+## Basic Workflow
+
+Run checks through the sandbox:
 
 ```bash
 openghost sandbox status
@@ -66,7 +84,7 @@ openghost script run web-baseline -- --target-url https://target.example
 openghost script run api-inventory -- --target-url https://target.example
 ```
 
-Record evidence and produce a report:
+Record evidence and generate a report:
 
 ```bash
 openghost evidence add --path response.txt --kind response --title "Baseline response"
@@ -76,34 +94,30 @@ openghost finding add \
   --priority P3 \
   --module server-integrity \
   --url "https://target.example/" \
-  --evidence E-001 \
   --confidence 95 \
+  --evidence E-001 \
   --step "Captured the baseline response." \
   --impact "Documented confirmed behavior." \
-  --priority-rationale "P3 because impact is limited and no sensitive data exposure was proven." \
+  --priority-rationale "P3 because impact is limited." \
   --remediation "Apply the recommended hardening."
 openghost report generate
 ```
 
-## Using With AI Agents
-
-Point the agent at `skills/openghost-skill/SKILL.md` or install the skill with a compatible skill manager. The skill tells the agent when to load deeper reference files and how to keep all tool execution inside Docker.
+## Reference
 
-Examples:
+### Skill Package
 
-```bash
-codex --instructions "Read skills/openghost-skill/SKILL.md and prepare an authorized assessment plan for https://target.example"
-```
-
-```bash
-gemini "Read skills/openghost-skill/SKILL.md and help initialize an OpenGhost engagement for https://target.example"
-```
-
-For agents that auto-discover Agent Skills, install the package and ask for an authorized web app assessment. The `description` field in `SKILL.md` is the trigger surface.
-
-## CLI Overview
+- `skills/openghost-skill/SKILL.md` - agent-facing entrypoint and workflow.
+- `skills/openghost-skill/references/` - deeper workflow, tooling, auth,
+  reporting, risk triage, threat modeling, and module guidance.
+- `skills/openghost-skill/references/modules/` - assessment modules for surface
+  mapping, session auth, access control, injection, APIs, browser policy, HTTP
+  edge cases, business logic, and server integrity.
+- `skills/openghost-skill/scripts/` - launcher, state helper, verification, and
+  reusable automation.
+- `skills/openghost-skill/assets/` - scope, auth, finding, and report templates.
 
-Sandbox lifecycle:
+### Sandbox Commands
 
 ```bash
 openghost sandbox start
@@ -113,7 +127,7 @@ openghost sandbox update
 openghost sandbox shell
 ```
 
-Run tools inside Docker:
+### Tool Execution
 
 ```bash
 openghost run <tool> [args...]
@@ -122,7 +136,7 @@ openghost python code '<script>'
 openghost python file <path> -- [args...]
 ```
 
-ZAP and browser workflows:
+### ZAP And Browser Workflows
 
 ```bash
 openghost zap start
@@ -132,18 +146,17 @@ openghost zap alerts --format md
 openghost browser devtools --url https://target.example --zap
 ```
 
-Engagement helpers:
+### Engagement Helpers
 
 ```bash
-openghost engagement init --url <url> --name <name>
 openghost todo add --task "Complete surface mapping" --module surface-map --priority high
 openghost evidence add --path <file> --kind <kind> --title <title>
 openghost artifact add --path <file> --kind <kind> --title <title>
-openghost finding add --title <title> --severity <severity> --module <module> --url <url> --confidence <90-100> --priority <P0-P4> --priority-rationale <text> --evidence E-001
+openghost finding add --title <title> --severity <severity> --module <module> --url <url> --confidence <90-100> --evidence E-001
 openghost report generate
 ```
 
-Script templates:
+### Script Templates
 
 ```bash
 openghost script list
@@ -152,19 +165,20 @@ openghost script copy xss-check
 openghost script run cors-check -- --base-url https://target.example --endpoints /api/me /
 ```
 
-Run `openghost help` for the complete command list.
-
-## Repository Layout
+## Repository Map
 
 ```text
 .
+|-- README.md
+|-- ARCHITECTURE.md
+|-- DEVELOPMENT.md
 |-- AGENTS.md
+|-- CONTRIBUTING.md
+|-- SECURITY.md
 |-- Dockerfile
-|-- README.md
-|-- developer/
-|   `-- docker/
+|-- docker/
 |-- openghost
-|-- runtime/
+|-- skills.sh.json
 `-- skills/
     |-- openghost
     `-- openghost-skill/
@@ -178,126 +192,29 @@ Run `openghost help` for the complete command list.
             `-- pentest/
 ```
 
-Important paths:
-
-- `skills/openghost-skill/SKILL.md` - skill manifest and operator workflow.
-- `skills/openghost-skill/references/` - deeper workflow, tooling, auth, reporting, and module guidance.
-- `skills/openghost-skill/references/modules/` - focused assessment modules.
-- `skills/openghost-skill/scripts/openghost.sh` - canonical launcher and Docker sandbox implementation.
-- `skills/openghost-skill/scripts/pentest/` - bundled reusable script templates.
-- `skills/openghost-skill/assets/` - scope, auth, finding, and report templates.
-- `developer/docker/Dockerfile` - maintainer image source for the sandbox.
-- `Dockerfile` - published-image delegate for normal users.
-
-## Agent Skill Structure
-
-OpenGhost follows the Agent Skills format used by modern agent clients:
-
-```text
-openghost-skill/
-|-- SKILL.md        # Required metadata and instructions
-|-- scripts/        # Executable helpers for deterministic work
-|-- references/     # Documentation loaded by agents only when needed
-`-- assets/         # Templates and reusable output resources
-```
-
-`SKILL.md` contains YAML frontmatter with `name`, `description`, `license`, and metadata. Keep this file focused on discovery, safety rules, setup, and the high-level workflow. Put detailed methodology in `references/`, deterministic helpers in `scripts/`, and reusable templates in `assets/`.
+## Developer Docs
 
-## Security Model
+- [Architecture](ARCHITECTURE.md) - components, command flow, trust boundaries,
+  and engagement state.
+- [Development](DEVELOPMENT.md) - local setup, validation commands, and release
+  checklist.
+- [AGENTS.md](AGENTS.md) - coding-agent maintenance context.
+- [Contributing](CONTRIBUTING.md) - contribution rules and pull request
+  expectations.
+- [Security](SECURITY.md) - vulnerability reporting policy.
+- [Attribution](ATTRIBUTION.md) - attribution and provenance notes.
 
-OpenGhost is designed for authorized assessments:
+## Safety Model
 
-- Confirm authorization, allowed targets, exclusions, rate limits, and test windows before testing.
+- Confirm authorization, targets, exclusions, rate limits, and test windows
+  before testing.
 - Set `OPENGHOST_SCOPE` and verify scope before running tests.
 - Run security tooling through `openghost`, not directly on the host.
-- Keep destructive, high-volume, or state-changing tests disabled unless explicitly authorized.
 - Treat scanner output as leads until validated with evidence.
 - Keep generated engagement data under `.openghost/` and normally out of commits.
-
-The sandbox mounts the current workspace at `/workspace`, drops unnecessary capabilities, and exposes tools through the launcher allowlist.
-
-## Developer Guide
-
-### Validate local changes
-
-For documentation-only changes:
-
-```bash
-rg -n "old command|wrong path" README.md AGENTS.md skills/openghost-skill
-```
-
-For shell changes:
-
-```bash
-bash -n openghost
-bash -n skills/openghost
-bash -n skills/openghost-skill/openghost
-bash -n skills/openghost-skill/scripts/openghost.sh
-bash -n skills/openghost-skill/scripts/verify-toolchain.sh
-```
-
-For Python changes:
-
-```bash
-python3 -m py_compile skills/openghost-skill/scripts/select-modules.py
-python3 -m py_compile skills/openghost-skill/scripts/openghost-state.py
-```
-
-For sandbox/runtime changes:
-
-```bash
-./openghost sandbox status
-./skills/openghost-skill/scripts/verify-toolchain.sh
-```
-
-### Add or update a sandbox tool
-
-1. Install the tool in `developer/docker/Dockerfile`.
-2. Add it to `ALLOWED_TOOLS` in `skills/openghost-skill/scripts/openghost.sh` if agents should run it directly.
-3. Add it to `skills/openghost-skill/scripts/verify-toolchain.sh` if it is required.
-4. Document operator usage in `SKILL.md`, `references/tooling.md`, or the relevant module file.
-5. Keep the root `Dockerfile` as a delegate to the published image.
-
-Build a local developer image when needed:
-
-```bash
-OPENGHOST_BUILD=1 OPENGHOST_IMAGE=openghost-sandbox:dev ./openghost sandbox update
-```
-
-### Add or update a module
-
-1. Add module guidance under `skills/openghost-skill/references/modules/`.
-2. Keep the module focused on one assessment area.
-3. Link it from `SKILL.md` only where agents need to discover it.
-4. Update `skills/openghost-skill/references/module-map.md` if module selection changes.
-5. Update `skills/openghost-skill/scripts/select-modules.py` if automatic selection should include the module.
-
-### Add or update a script template
-
-1. Add the script under `skills/openghost-skill/scripts/pentest/`.
-2. Give it safe defaults and clear `--help` output.
-3. Add its metadata to `skills/openghost-skill/scripts/pentest/manifest.json`.
-4. Run it only through `openghost script run` or `openghost python file`.
-5. Treat output as evidence to validate, not as an automatically confirmed finding.
-
-### Publish and registry notes
-
-The project is installable by skill managers that can read GitHub repositories with a `skills/` directory. For `skills.sh` compatibility:
-
-- Keep `skills/openghost-skill/SKILL.md` frontmatter valid.
-- Make the `description` field explicit about what the skill does and when agents should use it.
-- Keep references relative to the skill root.
-- Avoid duplicating long methodology in both `SKILL.md` and `references/`.
-- Keep scripts, references, and assets organized by purpose.
-
-The sandbox image is built from `developer/docker/Dockerfile` by the GitHub Actions workflow in `.github/workflows/publish-sandbox-image.yml`.
+- Use destructive, high-volume, or state-changing checks only when the rules of
+  engagement explicitly allow them.
 
 ## License
 
 OpenGhost is licensed under the Apache License 2.0. See [LICENSE](LICENSE).
-
-## References
-
-- [Agent Skills overview](https://agentskills.io/)
-- [Open Agent Skills specification](https://openagentskills.dev/docs/specification)
-- [skills.sh documentation](https://www.skills.sh/docs)
diff --git a/SECURITY.md b/SECURITY.md
new file mode 100644
index 0000000..dd33d2e
--- /dev/null
+++ b/SECURITY.md
@@ -0,0 +1,40 @@
+# Security Policy
+
+OpenGhost is security tooling, so vulnerability reports need enough detail to reproduce safely without exposing targets or third-party systems.
+
+## Supported Versions
+
+Security fixes are handled on the `main` branch until the project publishes versioned releases.
+
+## Reporting a Vulnerability
+
+Use GitHub private vulnerability reporting for this repository when available. Do not open a public issue with exploit details, credentials, target data, or sensitive evidence.
+
+Include:
+
+- Affected commit, release, or sandbox image digest.
+- Reproduction steps using only local fixtures, disposable labs, or intentionally vulnerable targets.
+- Expected and actual behavior.
+- Impact and any safe proof-of-concept output.
+- Whether any secret, credential, customer data, or third-party target was involved.
+
+If private vulnerability reporting is not available, open a public issue that says a private security report is needed, but do not include exploit details.
+
+## Scope
+
+In scope:
+
+- OpenGhost launcher and engagement-state helpers.
+- Skill instructions, bundled scripts, references, and templates.
+- Published sandbox image build configuration.
+- CI/CD configuration in this repository.
+
+Out of scope:
+
+- Findings in third-party systems tested with OpenGhost.
+- Vulnerabilities in upstream security tools unless OpenGhost packages or invokes them unsafely.
+- Reports that require destructive testing outside an authorized lab.
+
+## Disclosure
+
+Maintainers will acknowledge valid reports, triage impact, and publish fixes or mitigations before public disclosure when practical. Reporters should avoid accessing data beyond the minimum proof needed and should delete any sensitive evidence after resolution unless legal or contractual obligations require retention.
diff --git a/developer/docker/Dockerfile b/docker/Dockerfile
similarity index 100%
rename from developer/docker/Dockerfile
rename to docker/Dockerfile
diff --git a/developer/docker/healthcheck.sh b/docker/healthcheck.sh
similarity index 100%
rename from developer/docker/healthcheck.sh
rename to docker/healthcheck.sh
diff --git a/skills/openghost-skill/references/tooling.md b/skills/openghost-skill/references/tooling.md
index 0eff028..3202bf1 100644
--- a/skills/openghost-skill/references/tooling.md
+++ b/skills/openghost-skill/references/tooling.md
@@ -22,7 +22,7 @@ openghost sandbox update
 openghost sandbox shell
 ```
 
-The launcher pulls `ghcr.io/vaibhavsing/openghost-sandbox:latest` by default when the image is missing. Set `OPENGHOST_IMAGE` to override the image. Normal skill users should not build a Dockerfile locally; maintainers build and publish the sandbox from the repo's developer-only Docker context.
+The launcher pulls `ghcr.io/vaibhavsing/openghost-sandbox:latest` by default when the image is missing. Set `OPENGHOST_IMAGE` to override the image. Normal skill users should not build a Dockerfile locally; maintainers build and publish the sandbox from the repo's Docker context.
 
 ## Execution Commands
 
@@ -106,8 +106,8 @@ Developer-only local image builds are explicit opt-in:
 ```bash
 OPENGHOST_BUILD=1 \
   OPENGHOST_IMAGE=openghost-sandbox:dev \
-  OPENGHOST_DOCKERFILE=developer/docker/Dockerfile \
-  OPENGHOST_BUILD_CONTEXT=developer/docker \
+  OPENGHOST_DOCKERFILE=docker/Dockerfile \
+  OPENGHOST_BUILD_CONTEXT=docker \
   openghost sandbox start
 ```
 
diff --git a/skills/openghost-skill/scripts/__pycache__/select-modules.cpython-312.pyc b/skills/openghost-skill/scripts/__pycache__/select-modules.cpython-312.pyc
deleted file mode 100644
index 42e4112..0000000
Binary files a/skills/openghost-skill/scripts/__pycache__/select-modules.cpython-312.pyc and /dev/null differ
diff --git a/skills/openghost-skill/scripts/openghost.sh b/skills/openghost-skill/scripts/openghost.sh
index f32aa3c..0d69d6b 100755
--- a/skills/openghost-skill/scripts/openghost.sh
+++ b/skills/openghost-skill/scripts/openghost.sh
@@ -15,7 +15,7 @@ ZAP_API_KEY="${OPENGHOST_ZAP_API_KEY:-openghost}"
 ZAP_MAX_MEMORY="${OPENGHOST_ZAP_MAX_MEMORY:-1024m}"
 WORKSPACE_DIR="${OPENGHOST_WORKSPACE:-${PWD}}"
 OPENGHOST_HOME="${OPENGHOST_HOME:-${PWD}/.openghost}"
-DEV_DOCKER_DIR="${REPO_ROOT}/developer/docker"
+DEV_DOCKER_DIR="${REPO_ROOT}/docker"
 DOCKERFILE_PATH="${OPENGHOST_DOCKERFILE:-${DEV_DOCKER_DIR}/Dockerfile}"
 BUILD_CONTEXT="${OPENGHOST_BUILD_CONTEXT:-${DEV_DOCKER_DIR}}"