diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000..337374f81a
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,34 @@
+# rhdh
+
+Enterprise-grade Internal Developer Portal based on Backstage, with dynamic plugin support.
+
+## Build & Test Commands
+
+- Install: `yarn install`
+- Build all: `yarn build`
+- Dev (frontend + backend): `yarn dev`
+- Start (backend only): `yarn start`
+- Test all: `yarn test`
+- Lint check: `yarn lint:check`
+- Lint fix: `yarn lint:fix`
+- Type check: `yarn tsc`
+- Format check: `yarn prettier:check`
+- Format fix: `yarn prettier:fix`
+- Single-file lint: `npx eslint <path/to/file.ts>`
+- Single-file type check: `yarn tsc --noEmit` (from the relevant package directory)
+- Clean: `yarn clean`
+
+Turborepo is used for task orchestration. Scope to a single package with `--filter`:
+
+```bash
+yarn build --filter=backend
+yarn test --filter=@internal/plugin-scalprum-backend
+```
+
+## Key Conventions
+
+<!-- 3-5 rules the agent can't infer from the code itself -->
+
+## Architecture
+
+<!-- Where to find things that aren't obvious from directory names -->
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000000..43c994c2d3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/README.md b/README.md
index f3b4767ab3..5b304170b4 100644
--- a/README.md
+++ b/README.md
@@ -48,7 +48,15 @@ Our current list of plugins include:
 
 ## Getting Started
 
-Dependencies:
+### Quick Start
+
+```bash
+corepack enable   # Enable Yarn via corepack (one-time)
+yarn install      # Install all dependencies
+yarn dev          # Start frontend + backend
+```
+
+### Prerequisites
 
 - [Node.js](https://nodejs.org/en/) - [required version](.nvmrc)
 - [corepack](https://github.com/nodejs/corepack)
@@ -59,6 +67,19 @@ We are excited to see people wanting to contribute to our project and welcome an
 
 We also welcome non code contributions in the form of bug reporting and documentation writing. If you run across any bugs, please raise an issue here in [JIRA](https://issues.redhat.com/browse/RHDHBUGS).
 
+## Usage
+
+After completing setup, start the application locally:
+
+```bash
+yarn dev        # Start both frontend and backend (recommended for development)
+yarn start      # Start backend only
+```
+
+The frontend is available at `http://localhost:3000` and the backend at `http://localhost:7007`.
+
+For production deployments on OpenShift, see the [Getting Started documentation](https://github.com/redhat-developer/rhdh/blob/main/docs/index.md).
+
 ## Community, Discussion, and Support
 
 [Bugs](https://issues.redhat.com/projects/RHDHBUGS) should be filled out here on RHDHBUGS Jira.