docs(repo): meet the org repo-standard gate — 0 ERROR

Ran `repo-standard` (v0.1.1, class `standalone`) and fixed everything it
flagged as ERROR, plus the WARN links that were genuinely dead.

README first screen:
- opening line is now byte-identical to the forge description, so
  description == catalog == README is machine-checkable (badges moved below).
- `## Install` (required for class `standalone`): clone + `uv sync`, stated as
  clone-only because the shared spec, persona skill and example bundles under
  `shared/` are read from the working tree at run time. `uv run pytest` named as
  the verification, with the fact that no CI runner exists said out loud rather
  than implied by a badge.
- `## Non-goals` (required): the five limits already binding in CLAUDE.md —
  not a compliance product, not a portfolio-level reallocator, not autonomous
  decision-making, not turnkey, not a model benchmark.

Dead relative links (measured, not guessed):
- `docs/plan/2026-07-10-sesjonsplan-fase2-6.md` pointed at
  `../2026-07-14-revisjonspakke-DF-DI.md` six times; the file sits in
  `docs/plan/`, not `docs/`. (The sibling `../review-2026-07.md` links are
  correct and untouched.)
- the Fase-1 spike brief linked repo-root-relative from
  `.claude/projects/…/`; re-anchored with `../../../`.

The one remaining README ERROR was a gate false positive: `checkInternalLinks`
resolves targets against `git ls-files`, which lists files only, so a link to a
directory can never resolve. `[shared/](shared/)` now points at
`shared/README.md` — a better target anyway, since that file carries the
pull-only subtree rule. Not fixed here: the classifier lives in another repo.

Remaining WARNs are all inside `shared/`, deliberately untouched: it is a
pull-only commons subtree, and the nav-golden files are byte-level fixtures
that gate `test_nav_golden_*` — four of them are OKF bundle-internal links,
and the `/etc/passwd` ones are the negative escape fixture doing its job.

Suite green: 630 passed, 4 skipped (markdown-only diff; no test touched).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ri3aVJPfynCZtHRhesCzUH

README.md

@@ -1,5 +1,7 @@
 # portfolio-optimiser
 
+Generic, open framework on Microsoft Agent Framework (MAF): multi-agent cost-saving proposals gated by a mandatory deterministic validator, with HITL learning.
+
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Python](https://img.shields.io/badge/python-%E2%89%A53.10-blue.svg)](pyproject.toml)
 [![Built on Microsoft Agent Framework](https://img.shields.io/badge/built%20on-Microsoft%20Agent%20Framework-0078D4.svg)](https://github.com/microsoft/agent-framework)
@@ -10,6 +12,45 @@ generates candidate measures; a **mandatory deterministic validator** (solver +
 decides the numbers; domain experts judge the outcomes (human-in-the-loop); and the system
 **learns from their verdicts** across runs.
 
+## Install
+
+Python ≥3.10, with [`uv`](https://docs.astral.sh/uv/). The package is not published to a package
+index — install it from source:
+
+```bash
+git clone https://git.fromaitochitta.com/open/portfolio-optimiser.git
+cd portfolio-optimiser
+uv sync
+```
+
+Clone rather than install into an existing environment: the shared spec, the persona skill and the
+example bundles under [`shared/`](shared/README.md) are read from the working tree at run time.
+
+Verify the install by running the whole suite from the clean clone:
+
+```bash
+uv run pytest
+```
+
+There is no CI runner in this organization, so nothing runs that suite automatically — the command
+above is the verification.
+
+## Non-goals
+
+- **Not a compliance product.** It ships the technical prerequisites — local-only operation,
+  provenance on every proposal, no silent data egress — and stops there. Processing purpose, DPIA
+  and risk assessment stay with the deploying organization.
+- **Not a portfolio-level reallocator.** It finds savings *inside* each project. Moving budget
+  between projects, ranking projects against one another and portfolio governance sit above the
+  method and are out of scope.
+- **Not autonomous decision-making.** The deterministic validator can only block; approving a
+  measure is a domain expert's call (human-in-the-loop), and the framework implements nothing on
+  the agents' say-so.
+- **Not a turnkey vertical solution.** The aim is a generic core with explicit extension points
+  (data sources, cost models, personas) — not the last 10% of any one domain.
+- **Not a model benchmark.** The end-to-end proof runs offline against a scripted stand-in client:
+  it shows that the loop closes, not how well a given LLM proposes or judges.
+
 > **Status:** the full 8-step agentic loop is wired and proven with load-bearing tests, and the
 > end-to-end proof is an **offline simulation** with a scripted stand-in client — no live-model
 > run yet. The **ingest layer** (real data sources) is implemented — file/CSV and SQL on both
@@ -89,7 +130,7 @@ when the seam is detached, so the loop cannot silently degrade into theater.
 
 ## How it is set up
 
-- **One shared, framework-neutral core** ([`shared/`](shared/), a git subtree of
+- **One shared, framework-neutral core** ([`shared/`](shared/README.md), a git subtree of
   [`portfolio-optimiser-commons`](https://git.fromaitochitta.com/ktg/portfolio-optimiser-commons)):
   the business concept, the normative [method spec](shared/method-spec.md) and
   [ingest spec](shared/ingest-spec.md), the expert-reviewer persona as an Agent Skill, and an