docs: release prep for v0.0.1

.github/workflows/ci.yml

@@ -10,9 +10,9 @@ jobs:
   build-and-test:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        runner: [arc-runner-unityinflow, orangepi]
         node-version: [18, 20]
-    runs-on: ${{ matrix.os }}
+    runs-on: ${{ matrix.runner }}
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to spec-linter
+
+## Adding a New Rule
+
+1. Create `src/rules/SXXX-rule-name.ts` implementing the `Rule` interface
+2. Create `tests/rules/SXXX.test.ts` with at least 3 passing and 3 failing cases
+3. Register the rule in `src/rules/index.ts`
+4. Update `README.md` rules table
+5. Run `npm test` — all green
+6. Submit a PR with the rule name in the title
+
+## Rule Interface
+
+```typescript
+import { Rule, LintResult, ParsedSpecFile } from '../types.js';
+
+export const myRule: Rule = {
+  id: 'SXXX',
+  name: 'rule-name',
+  severity: 'error', // or 'warning'
+  description: 'What this rule checks',
+  check(file: ParsedSpecFile): LintResult[] {
+    // Return array of issues found
+    return [];
+  },
+};
+```
+
+## Development
+
+```bash
+npm install          # install deps
+npm test             # run tests
+npm run test:watch   # watch mode
+npm run build        # build to dist/
+npm run lint         # type check
+```
+
+## Commit Convention
+
+```
+feat: add SXXX rule-name rule
+fix: S001 false positive on nested headers
+test: add edge cases for empty file input
+docs: update README with SXXX examples
+```

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiri Hermann / UnityInFlow
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -2,15 +2,95 @@
 
 > Lint CLAUDE.md and AI spec files — catches missing sections, secrets, and context bloat.
 
-**Status:** Under construction
+## The Problem
 
-## What this does
+CLAUDE.md, GEMINI.md, and AI spec files are written by hand with zero validation. Common mistakes:
 
-spec-linter validates AI agent spec files (CLAUDE.md, GEMINI.md, GSD specs) for structural problems that silently degrade agent performance.
+- Missing required sections — the agent builds the wrong thing
+- Accidentally committed API keys — security breach waiting to happen
+- 80kb spec files — context window saturated, agent performance degrades
+
+These mistakes degrade agent performance **silently**. No error is thrown. The agent just produces subtly wrong output.
+
+## Examples of Errors Caught
+
+**Missing required sections:**
+```
+$ spec-linter check my-project/CLAUDE.md
+
+my-project/CLAUDE.md
+  error  Missing required section: "Project Overview"  (S001)
+  error  Missing required section: "Acceptance Criteria"  (S001)
+
+2 error(s), 0 warning(s)
+```
+
+**Accidentally committed secret:**
+```
+$ spec-linter check my-project/CLAUDE.md
+
+my-project/CLAUDE.md
+  :15 error  Possible OpenAI/Anthropic API key detected. Remove before committing.  (S003)
+
+1 error(s), 0 warning(s)
+```
+
+**Wildcard tool permissions:**
+```
+$ spec-linter check my-project/CLAUDE.md
+
+my-project/CLAUDE.md
+  :42 error  Wildcard tool permission (Tool(*:*)) — use explicit tool names instead of wildcards.  (S005)
+
+1 error(s), 0 warning(s)
+```
 
 ## Installation
 
-Coming soon — `npm install -g @unityinflow/spec-linter`
+```bash
+npm install -g @unityinflow/spec-linter
+```
+
+Or run directly:
+
+```bash
+npx @unityinflow/spec-linter check CLAUDE.md
+```
+
+## Usage
+
+```bash
+# Lint a specific file
+spec-linter check CLAUDE.md
+
+# Lint all spec files in current directory
+spec-linter check .
+
+# JSON output for CI
+spec-linter check CLAUDE.md --format json
+
+# Only show errors
+spec-linter check CLAUDE.md --quiet
+
+# List available rules
+spec-linter rules
+```
+
+## Rules
+
+| ID | Name | Severity | Description |
+|---|---|---|---|
+| S001 | required-sections | error | Must have: Project Overview, Constraints, Acceptance Criteria |
+| S003 | no-secrets | error | No API keys, tokens, or private keys |
+| S004 | file-size | warning | >30kb warns, >50kb errors (context bloat) |
+| S005 | no-wildcard-permissions | error | No `Bash(*:*)` or `"*"` in tool permissions |
+| S006 | no-duplicate-headers | warning | No duplicate section headings at same level |
+
+## Exit Codes
+
+- `0` — all checks passed
+- `1` — errors found
+- `2` — warnings only
 
 ## License