docs: clarify per-finding exposure logic

src/server/routes/surface.rs

@@ -3,9 +3,12 @@
 //! Loads the map persisted by the most recent indexed scan from
 //! SQLite, falling back to building a fresh entry-point-only map from
 //! the on-disk source when no scan has populated one yet.  The
-//! response shape is the canonical `SurfaceMap` JSON — identical to
-//! `nyx surface --format json` — so the frontend can reuse the same
-//! deserialisation in both surfaces.
+//! response is the canonical `SurfaceMap` JSON (the same `nodes` +
+//! `edges` shape `nyx surface --format json` emits, so the frontend
+//! reuses the same `SurfaceMap` deserialiser) plus one extra
+//! top-level `entry_risks` array — the per-entry-point risk
+//! assessment the CLI prints as a banner rather than serialising.
+//! Consumers that only need the map ignore the extra key.
 
 use crate::commands::surface::load_or_build;
 use crate::server::app::AppState;

src/surface/mod.rs

@@ -87,9 +87,13 @@ pub enum Framework {
 /// Every node carries the route's declared path string, HTTP method,
 /// and a resolved handler [`SourceLocation`] pointing at the function
 /// definition.  `auth_required` is `true` when the decorator stack
-/// (or framework equivalent) contains an auth guard the probe was
-/// able to identify; Phase 21 recognises Flask's `@login_required`,
-/// `@auth_required`, and `@jwt_required` decorators.
+/// (or framework equivalent — annotation, middleware argument, or a
+/// body-level guard call) contains an auth marker the probe was able
+/// to identify.  The marker set is the per-framework registry in
+/// [`crate::auth_analysis::auth_markers`] (e.g. Flask's
+/// `@login_required` / `@auth_required` / `@jwt_required` /
+/// `@token_required` / `@requires_auth` / `@authenticated` /
+/// `@require_login`), not a fixed three-decorator list.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct EntryPoint {
     pub location: SourceLocation,

src/surface/risk.rs

@@ -36,8 +36,12 @@ impl RiskTier {
     /// * the same route behind auth is `High` (40 ≥ 35);
     /// * an unauthenticated route writing a SQL store is `High`
     ///   ((15 + 5) × 1.5 + 5 = 35 ≥ 35);
-    /// * a route that only reads a store or talks to one service is
-    ///   `Medium`;
+    /// * an unauthenticated route that only reads a SQL store
+    ///   (15 × 1.5 + 5 = 27) or talks to one external service
+    ///   (8 × 1.5 + 5 = 17) is `Medium`;
+    /// * the same single read / single egress *behind auth* (no ×1.5
+    ///   scaling) usually stays `Low` — an auth-gated KV/document read
+    ///   (10) or one external call (8) is below the 12 threshold;
     /// * a route with no reachable destination at all is `Low`.
     pub fn from_score(score: f64) -> Self {
         if score >= 60.0 {