Add open source project guidance

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to REA
+
+REA welcomes focused bug fixes, documentation improvements, tests, and reverse-engineering workflow enhancements. Open an issue before a large contract or architecture change so its scope can be agreed before implementation.
+
+## Development setup
+
+REA requires macOS 12 or newer, Node.js 22 or newer, and a separately installed Hopper Disassembler application for real-Hopper verification.
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+Keep dependencies flowing inward through the existing domain, Hopper, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the 31 direct, 8 enhanced, and 3 session tools unless a deliberate contract change updates every verifier and snapshot.
+
+Before submitting a pull request, run:
+
+```bash
+npm run check
+npm run verify:package
+npm pack --dry-run
+```
+
+Changes that claim real Hopper behavior must also be tested against two distinct binaries:
+
+```bash
+HOPPER_TARGET_PATH=/path/to/target-a \
+HOPPER_SECOND_TARGET_PATH=/path/to/distinct-target-b \
+npm run verify:hopper
+```
+
+Describe the behavior change and verification performed in the pull request. Never commit binaries, Hopper documents, credentials, `dist/`, `node_modules/`, or local planning artifacts.
+
+## Maintainer release checklist
+
+Run the full checks, isolated package verifier, package dry run, and two-target real-Hopper verifier described above. Build a local tarball and exercise the executable through the package boundary:
+
+```bash
+npm pack
+npm exec --yes --package ./morluto-rea-0.1.0.tgz -- rea --help
+```
+
+Publish the public scoped package:
+
+```bash
+npm publish --access public
+```
+
+After npm registry propagation, verify the published CLI and connect a beta.3 MCP client to the published server to confirm all 42 tools:
+
+```bash
+npx -y @morluto/rea --help
+npx -y @morluto/rea doctor
+npx -y @morluto/rea setup --yes
+npx -y @morluto/rea mcp
+```

README.md

@@ -1,9 +1,13 @@
 # REA
 
+[npm package](https://www.npmjs.com/package/@morluto/rea) · [Issues](https://github.com/morluto/rea/issues) · [Hopper Disassembler](https://www.hopperapp.com/)
+
 REA gives coding agents access to Hopper Disassembler through one `rea` command. It exposes 42 MCP tools: 31 direct Hopper operations, 8 composed analysis workflows, and 3 target-session tools.
 
 REA uses Hopper's public Python API through its own authenticated local bridge. It does not use Hopper's bundled MCP server.
 
+**REA is not a disassembler.** Hopper Disassembler is a separate macOS dependency that must be installed and licensed independently. REA launches and controls Hopper underneath through its public Python API.
+
 ## Requirements
 
 - macOS 12 or newer
@@ -14,13 +18,16 @@ REA does not bundle Hopper. `rea setup --yes` can install Homebrew when absent,
 
 ## Install
 
-After publication:
+Quick start:
 
 ```bash
 npx -y @morluto/rea setup --yes
 npx -y @morluto/rea doctor
+npx -y @morluto/rea mcp
 ```
 
+The final command starts the stdio MCP server for clients that launch it directly. `setup` can write the equivalent persistent client registration automatically.
+
 For source-checkout development:
 
 ```bash
@@ -94,14 +101,9 @@ npm run verify:hopper
 
 Real-Hopper verification requires Hopper and two distinct binaries. It checks target-free startup, all 42 tools, analysis, bounded decompilation, target switching, bridge cleanup, and server shutdown. The verifier terminates only Hopper bundle processes that appeared during its run; it preserves Hopper processes that were already running.
 
-Before publishing a release, run `npm run check`, `npm run verify:package`, `npm pack --dry-run`, and the two-target real-Hopper verifier. After publication, repeat the CLI and MCP smoke tests through `npx -y @morluto/rea`.
+The npm package is named `@morluto/rea`, while the product and installed executable remain `REA` and `rea`. Setup writes a floating MCP registration using `npx -y @morluto/rea mcp`. See [CONTRIBUTING.md](CONTRIBUTING.md) for the release checklist and local-tarball verification workflow.
 
-The npm package is named `@morluto/rea`, while the product and installed executable remain `REA` and `rea`. Setup writes a floating MCP registration using `npx -y @morluto/rea mcp`. A local tarball exercises the same package boundary before publication:
-
-```bash
-npm pack
-npm exec --yes --package ./morluto-rea-0.1.0.tgz -- rea --help
-```
+Security reports should follow [SECURITY.md](SECURITY.md).
 
 ## License
 

SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest published version of REA. Upgrade to the latest release before reporting a problem that may already have been resolved.
+
+## Reporting a vulnerability
+
+Do not disclose vulnerabilities, proof-of-concept exploits, credentials, private binaries, or Hopper documents in a public issue.
+
+If private vulnerability reporting is available in the repository's **Security** tab, use **Report a vulnerability**. Otherwise, open a minimal issue asking the maintainer to establish a private contact channel; include no sensitive technical details in that issue.
+
+Include the affected REA version, macOS and Hopper versions, impact, reproduction conditions, and any suggested mitigation in the private report. Remove credentials, proprietary binaries, Hopper documents, socket capability tokens, and unrelated local paths from logs or examples.
+
+The maintainer will acknowledge the report, assess its scope, and coordinate remediation and disclosure timing with the reporter. Please allow time for Hopper-dependent behavior to be reproduced safely.
+
+## Security boundary
+
+REA authenticates each local bridge session with a random capability token and a current-user Unix socket. This is not a sandbox and does not protect against malicious processes already running as the same macOS user. Opening an untrusted binary delegates parsing and analysis to Hopper with that user's permissions.