docs(portal): clean and align documentation guidance
cognitive committed
Mar 3, 2026 at 20:13 UTC
cb0b43753d4606fbc8a9e15c764601f6705a92f2
3 files changed
+25
-12
AGENTS.md
+6
-5
@@ -34,15 +34,16 @@ Source of truth for architecture decisions: `docs/adr/README.md` and linked ADRs
34
35
## Operational Truths (CI-Aligned, Minimal)
36
37
-1. **Default local lint behavior is `make lint-auto`.**
38
- - Why: applies safe automatic rewrites before verification and reduces lint iteration churn.
37
+1. **Local lint workflow: run `make lint-auto` first, then `make lint`.**
38
+ - Why: `lint-auto` applies safe rewrites locally, while `lint` is the strict non-mutating gate that matches CI.
39
40
2. **Use CI-equivalent verification when validating high-risk changes:**
41
- - `make lint-auto`
41
+ - `make vet`
42
+ - `make lint`
43
- `make test`
43
- - `make tidy`
44
- `make vuln`
45
- Why: these are the enforced checks in `.github/workflows/ci.yml`.
46
+ - Note: `make tidy` is a local maintenance/pre-release step and is not currently part of the CI workflow.
47
48
3. **Assume Go toolchain baseline from `go.mod` (currently 1.26.x).**
49
- Why: CI resolves Go from `go.mod`; avoid stale version assumptions.
@@ -74,7 +75,7 @@ Source of truth for architecture decisions: `docs/adr/README.md` and linked ADRs
75
76
## Verbalized Sampling
77
77
-Before trival or non-trivial changes, AI agents **must**:
78
+Before trivial or non-trivial changes, AI agents **must**:
79
80
1. **Sample 3–5 intent hypotheses** — rank by likelihood, note one weakness each
81
2. **Explore edge cases** — at least 3 standard, 5 for architectural changes
README.md
+7
-1
@@ -81,7 +81,7 @@ Contributions are welcome.
81
82
### Verification (CI-Aligned)
83
84
-Run the same checks enforced in CI (`.github/workflows/ci.yml`):
84
+Run the same checks enforced in CI (`.github/workflows/ci.yml`) in this order:
85
86
```bash
87
make vet
@@ -90,6 +90,12 @@ make test
90
make vuln
91
```
92
93
+For local pre-PR cleanup (not enforced in CI), run:
94
+
95
+```bash
96
+make tidy
97
+```
98
+
99
### Steps to Contribute
100
1. Fork the repository
101
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
cmd/relay-server/frontend/README.md
+12
-6
@@ -100,12 +100,18 @@ Build output:
100
101
### NPM Scripts
102
103
-```bash
104
-npm run dev
105
-npm run build
106
-npm run lint
107
-npm run typecheck
108
-```
103
+| Script | Purpose |
104
+| --- | --- |
105
+| `npm run dev` | Start the Vite development server (`http://localhost:5173`). |
106
+| `npm run build` | Type-check and build production assets into `dist/`. |
107
+| `npm run lint` | Run ESLint with warnings treated as errors. |
108
+| `npm run typecheck` | Run TypeScript checking with `--noEmit`. |
109
+| `npm test` | Run the frontend test suite with `vitest run`. |
110
+| `npm run test:watch` | Run Vitest in watch mode for local TDD cycles. |
111
+| `npm run test:coverage` | Run Vitest with coverage reporting. |
112
+| `npm run preview` | Preview the production bundle with Vite. |
113
+| `npm run build:go` | Build the relay server binary used by local serve flow. |
114
+| `npm run serve` | Build frontend + Go binary, then launch relay server on admin port `4017`. |
115
116
## Relay Server Integration
117