docs: rewrite README with full feature/command reference

[rgdevme]

Summary

• Rewrites the README to cover what agnos is, what it solves, a full feature list, badges (CI, npm downloads, Node version, agent-friendly, license), the writer/reader model, installation, usage, the full agnos.json config shape, and per-domain command tables (docs/rules/skills/mcp/hooks/agents) sourced from the actual CLI command specs.
• Adds an active-development disclaimer and a contributing section matching the CI pipeline.
• Style: no em dashes, no self-attribution.

Test plan

• Render README.md on GitHub and confirm all anchor links in the table of contents resolve
• Spot-check the command tables against agnos <domain> --help output

[qodo-code-review]

PR Summary by Qodo

Rewrite README with full feature/config/command reference

📝 Documentation 🕐 20-40 Minutes

AI Description

• Expand README to explain agnos purpose, problems solved, and writer/reader model.
• Add end-to-end install/usage guidance plus full agnos.json field reference and examples.
• Document CLI commands per domain with tables, plus contributing/CI and active-development notes.

Diagram

graph TD
  A["CLI command specs"] --> B["README.md"] --> C["Users & contributors"]
  D["schema.json"] --> B
  E["CI pipeline"] --> B

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Auto-generate command tables from `--help` in CI

• ➕ Prevents README/CLI drift as commands evolve
• ➕ Reduces manual maintenance for large command matrices
• ➕ Can fail CI when docs are stale
• ➖ Adds doc-generation tooling and a release/docs workflow
• ➖ Help output formatting changes can create noisy diffs
• ➖ Harder to add explanatory nuance vs curated tables

2. Move deep reference docs into `/docs` and keep README as an overview

• ➕ Keeps README shorter and more scannable
• ➕ Allows richer structure (separate pages per domain/config topic)
• ➕ Easier long-term navigation as surface area grows
• ➖ More clicking for first-time users
• ➖ Requires additional docs site strategy (or accepted GitHub markdown navigation)
• ➖ README may still need a duplicated “quick reference”

Recommendation: The current approach (a comprehensive README) is appropriate if the goal is a single, GitHub-native onboarding + reference page. Given the volume of command/config surface documented, consider a follow-up to auto-generate (or at least validate) the command tables against agnos --help output in CI to reduce drift risk while keeping the curated narrative sections hand-written.

Files changed (1) +254 / -33

Documentation (1) +254 / -33

README.mdFull README rewrite with features, config schema, and per-domain commands +254/-33

Full README rewrite with features, config schema, and per-domain commands

• Replaces the README with a complete product overview (problem statement, features, and the writer/reader model), updated badges, and clearer installation/usage guidance. Adds full 'agnos.json' examples plus a field reference table, and documents global flags and per-domain CLI commands with tables, along with active-development and contributing/CI alignment updates.

README.md

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (1)

Context used

✅ Compliance rules (platform): 64 rules

✅ Skills: doc-authoring, doc-authoring-with-logs

1. README uses npm install commands ✓ Resolved 📘 Rule violation § Compliance

Description

The updated README includes npm install commands (npm i -g and npm i -D), which reintroduces a
disallowed package manager in primary documentation. This can cause contributor/tooling drift and
violates the requirement to use pnpm/pnpx exclusively.

Code

README.md[R98-103]

npm i -g @luxia/agnos
+
+# or per-project
+npm i -D @luxia/agnos
+pnpm add -D @luxia/agnos
+```

Relevance

⭐⭐⭐ High

Team accepted enforcing “pnpm-only” by removing npm commands in CI (PR #18).

PR-#18

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 704837 requires enforcing pnpm as the only package manager and explicitly flags
docs snippets using npm as failures. The README installation section contains `npm i -g
@luxia/agnos and npm i -D @luxia/agnos`.

Rule 704837: Enforce pnpm as the sole JavaScript package manager
README.md[98-103]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The README includes `npm` install commands, but the project requires `pnpm` as the sole JS package manager (including in documentation snippets).

## Issue Context
The compliance rule explicitly disallows `npm`/`npx` usage anywhere in changed files (including docs) unless an exception policy exists.

## Fix Focus Areas
- README.md[98-103]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. README duplicates agnos.json schema 📜 Skill insight ⚙ Maintainability

Description

The README reproduces the default and full agnos.json configuration blocks inline, which
duplicates canonical values already defined elsewhere (e.g., schema.json). This increases the risk
of documentation drifting from the actual code/schema.

Code

README.md[R132-146]

+```jsonc
+{
+  "$schema": "https://unpkg.com/@luxia/agnos/schema.json",
+  "schemaVersion": 1,
+  "agents": ["claude-code", "codex"],
+  "rules": {
+    "files": {
+      "./AGENTS.md": [],
+    },
+  },
+  "skills": {},
+  "mcp": [],
+  "docs": { "root": ".docs" },
+}
+```

Relevance

⭐⭐⭐ High

Team previously accepted removing duplicated authoritative rules text to avoid drift (PR #12);
likely same for schema/docs.

PR-#12

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1524833 prohibits documentation from containing code snippets/values that already
exist in code unless it is purely a reference. The README adds full inline JSONC examples for
agnos.json, rather than only pointing to the authoritative schema/source file.

README.md[132-146]
README.md[149-204]
Skill: doc-authoring

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The README includes large inline config/code snippets for `agnos.json` (default + full example). Compliance requires docs not to duplicate code/values that already exist in code; instead, docs should reference the authoritative source by path.

## Issue Context
This README already points to `schema.json` as authoritative, but it still reproduces full config blocks that are likely to drift as the schema evolves.

## Fix Focus Areas
- README.md[132-146]
- README.md[149-204]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Invalid agnos.json examples ✓ Resolved 🐞 Bug ≡ Correctness

Description

README’s agnos.json snippets include JSONC-only syntax (e.g., // comments and trailing commas),
but the CLI parses agnos.json with JSON.parse, so copy-pasting the examples will fail parsing
and block agnos runs.

Code

README.md[R132-146]

+```jsonc
+{
+  "$schema": "https://unpkg.com/@luxia/agnos/schema.json",
+  "schemaVersion": 1,
+  "agents": ["claude-code", "codex"],
+  "rules": {
+    "files": {
+      "./AGENTS.md": [],
+    },
+  },
+  "skills": {},
+  "mcp": [],
+  "docs": { "root": ".docs" },
+}
+```

Relevance

⭐⭐ Medium

No prior suggestions found about JSONC-in-README vs strict JSON.parse config parsing.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

agnos.json is parsed using JSON.parse (strict JSON), so JSONC features shown in the README
examples will cause parse failures.

src/core/config.ts[16-23]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
README documents `agnos.json` examples as `jsonc` (comments + trailing commas), but the implementation loads `agnos.json` using `JSON.parse`. Users who copy/paste the README examples into `agnos.json` will get a parse error and `agnos` will not run.

## Issue Context
- The README contains multiple ` ```jsonc ` blocks that include syntax not accepted by `JSON.parse`.
- The config loader explicitly calls `JSON.parse` and throws on invalid JSON.

## Fix Focus Areas
- README.md[132-204]

### What to change
- Replace the `jsonc` examples with valid JSON (remove `//` comments and remove trailing commas), OR
- Keep illustrative `jsonc` blocks but add an explicit warning that `agnos.json` must be strict JSON and the examples are not copy-pasteable as-is.
- Prefer providing at least one fully copy-pasteable minimal config snippet in strict JSON.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Symlink guidance misleading ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

README implies elevation is generally required to create symlinks and that non-elevated runs will
use hardlinks/copies, but the implementation attempts symlinks first and only falls back on specific
permission errors (and uses Windows directory junctions), so the guidance is
platform/permission-dependent.

Code

README.md[R114-118]

+> **NOTE**: We recommend running `agnos agents` from an elevated terminal the first time.
+>
+> This way, it will create sym-links during the agents rendering cycle. Using a non-elevated terminal will use hard links, and fall back to plain copy.
+>
+> Subsequent runs can be done without elevated priviledges, as the sym-links do not need to updated.

Relevance

⭐⭐ Medium

No historical review evidence found about README symlink/elevation guidance accuracy.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The link implementation tries fs.symlink(...) first and only falls back to hardlink/copy on
EPERM/EACCES, and the agent adapter messaging also frames elevation/Developer Mode as a
conditional requirement.

src/core/fs/link.ts[49-85]
src/agents/adapters/shared.ts[46-66]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The README’s symlink note is written as a general rule, but the actual linking behavior is conditional: agnos tries to create a symlink and only falls back to hardlink/copy when symlink creation fails due to permission errors (notably on Windows).

## Issue Context
- On Windows, directory linking uses junctions; file symlinks can require elevation/Developer Mode.
- On other platforms/environments, symlinks often work without elevation.

## Fix Focus Areas
- README.md[114-118]

### What to change
- Rewrite the note to say agnos will try to create symlinks automatically, and only if the environment disallows them it will fall back to hardlinks/copies.
- Make the elevation/Developer Mode guidance explicitly Windows-focused (or "when symlink creation is restricted") instead of universal.
- Optionally mention that agnos logs whether it hardlinked/copied so users can see what happened.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---