Skip to content

Commit 6065f5f

Browse files
ddavid37ddavid37
committed
Update AGENTS.md and add DEVELOPMENT.md for ClawdStrike Academy
- Revised AGENTS.md to direct contributors to the new DEVELOPMENT.md for setup and design guidelines. - Introduced DEVELOPMENT.md, detailing UI design requirements, local development instructions, and useful paths for contributors and AI agents. - Enhanced README.md to clarify the purpose of the document and link to the new DEVELOPMENT.md for contributor-specific information.
1 parent 253af6d commit 6065f5f

File tree

3 files changed

+94
-26
lines changed

3 files changed

+94
-26
lines changed

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ TypeScript packages are built/tested per-package (no root JS workspace):
2929
Docs:
3030
- `mdbook build docs` / `mdbook test docs`
3131

32-
**ClawdStrike Academy (`apps/academy`):** UI must follow `apps/academy/docs/design/DESIGN.md`. Develop with `npm install` at the repo root, then `npm run dev` in `apps/academy`.
32+
**ClawdStrike Academy (`apps/academy`):** Contributor and agent setup (design rules, `npm run dev`, notes) is in `apps/academy/DEVELOPMENT.md`. Visitor-facing overview is `apps/academy/README.md`.
3333

3434
## Coding Style & Naming Conventions
3535

‎apps/academy/DEVELOPMENT.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# ClawdStrike Academy — Development guide
2+
3+
This document is for **contributors**, **maintainers**, and **automation (including AI coding agents)** working in `apps/academy`.
4+
5+
**Visitors** looking for an overview of the product should read **[README.md](./README.md)** in this directory instead.
6+
7+
---
8+
9+
## UI / design (required)
10+
11+
All UI work in `apps/academy` **must** follow:
12+
13+
**[docs/design/DESIGN.md](./docs/design/DESIGN.md)**
14+
15+
That file is the design-system reference (colors, typography, shadows, layout, components). Read it before adding or changing pages, components, or global styles. When prompting an agent, point at that path explicitly.
16+
17+
**Fonts:** `DESIGN.md` references Waldenburg / Geist. The app currently uses **Cormorant Garamond** (300/600) for display and **JetBrains Mono** for code until licensed or self-hosted fonts are added (`src/app/layout.tsx`).
18+
19+
---
20+
21+
## Run locally
22+
23+
From the **repository root** (npm workspaces):
24+
25+
```bash
26+
npm install
27+
cd apps/academy
28+
npm run dev
29+
```
30+
31+
Open [http://localhost:3000](http://localhost:3000).
32+
33+
- **Node:** **24** matches root `package.json` `engines` (e.g. `mise install`, then `mise exec -- npm run dev` if you do not use 24 globally).
34+
- **`dev` script:** runs `prebuild` (ruleset extraction + source extraction) before `next dev`.
35+
36+
---
37+
38+
## Hydration / browser extensions
39+
40+
Extensions (e.g. **Grammarly**) may inject attributes on `<body>` before React hydrates. The root layout sets **`suppressHydrationWarning`** on **`<body>`** (and `<html>`) so those mismatches do not surface as hydration errors in development.
41+
42+
---
43+
44+
## Useful paths
45+
46+
| Path | Purpose |
47+
| ---- | ------- |
48+
| `src/app/` | Next.js App Router routes and layouts |
49+
| `src/components/` | UI and layout components |
50+
| `docs/design/DESIGN.md` | Visual design contract |
51+
| `images/` | Readme / marketing screenshots (e.g. `academy-readme-*.png`) |
52+
53+
---
54+
55+
## Workspace reference
56+
57+
Repo-wide conventions: **[AGENTS.md](../../AGENTS.md)** at the monorepo root (structure, Rust/TS norms, CI expectations). The Academy-specific UI rule above stays authoritative for this app’s look and feel.

‎apps/academy/README.md‎

Lines changed: 36 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,41 +1,52 @@
11
# ClawdStrike Academy
22

3-
Next.js app (`clawdstrike-academy`): interactive onboarding for the ClawdStrike runtime security system — lesson tracks, guard gallery, policy lab, and in-browser WASM demos.
3+
**Learn ClawdStrike by doing.** An interactive learning surface for the runtime security stack: guided tracks, a guard gallery, policy exercises, and a real policy engine compiled to **WebAssembly** — running in your browser.
44

5-
## Screenshots
5+
---
66

7-
Assets live in `[images/](./images/)`. Paths are relative to this README (`./images/…`).
7+
## What you’ll find here
88

9-
### Landing
9+
- **Learning tracks** — ordered lessons from first principles to deeper topics (threat scenarios, policy lab, guard deep-dives).
10+
- **Guard Gallery** — all built-in guards in one place, with tiered explanations and hands-on pages.
11+
- **Policy Lab** — edit YAML, compare rulesets, see inheritance — tied to how ClawdStrike actually evaluates policy.
12+
- **No separate install for readers** — when this app is hosted or you run it locally, the heavy lifting is the same engine the project ships, just behind a friendly UI.
1013

11-
Hero, primary CTAs, and learning tracks.
14+
---
1215

13-
### Guard Gallery
16+
## Preview
1417

15-
Tier sections and guard cards.
18+
<p align="center">
19+
<strong>Landing</strong> — hero, tracks, and calls to action
20+
</p>
21+
<p align="center">
22+
<img
23+
src="./images/academy-readme-landing.png"
24+
alt="ClawdStrike Academy landing: hero and learning tracks"
25+
width="1100"
26+
/>
27+
</p>
1628

17-
## UI / design (required)
29+
<p align="center">
30+
<strong>Guard Gallery</strong> — browse guards by tier
31+
</p>
32+
<p align="center">
33+
<img
34+
src="./images/academy-readme-guard-gallery.png"
35+
alt="ClawdStrike Academy Guard Gallery overview"
36+
width="1100"
37+
/>
38+
</p>
1839

19-
**All UI work in `apps/academy` must follow:**
40+
---
2041

21-
`[docs/design/DESIGN.md](docs/design/DESIGN.md)`
42+
## More about the project
2243

23-
That document is the design-system reference (colors, typography, shadows, layout, components). Read it before adding or changing pages, components, or global styles. When AI agents implement UI here, point them at that path.
44+
ClawdStrike is the wider **policy, receipts, and enforcement** system this Academy teaches. Start at the [repository root README](../../README.md) for install, architecture, and community links.
2445

25-
**Implementation note:** `DESIGN.md` references Waldenburg / Geist; the app uses **Cormorant Garamond** (300/600) for display and **JetBrains Mono** for code until licensed or self-hosted fonts are added.
46+
---
2647

27-
## Development
48+
## For contributors & tooling
2849

29-
From the repository root (npm workspaces):
50+
If you are **developing this app**, running it locally, or you are an **AI agent** changing UI or behavior, use the dedicated guide — it holds setup commands, design rules, and repo-specific notes:
3051

31-
```bash
32-
npm install
33-
cd apps/academy
34-
npm run dev
35-
```
36-
37-
Then open [http://localhost:3000](http://localhost:3000).
38-
39-
**Tooling:** Node **24** matches root `package.json` `engines` (e.g. `mise install` / `mise exec -- npm run dev`). The `dev` script runs a `prebuild` (ruleset + source extraction) before Next.js.
40-
41-
**Hydration noise in dev:** Some browser extensions (e.g. Grammarly) inject attributes on `<body>`. The root layout uses `suppressHydrationWarning` on `<body>` so that does not surface as a React hydration error.
52+
**[→ Development guide (Contributors & agents)](./DEVELOPMENT.md)**

0 commit comments

Comments
 (0)