docs(api): document GET /api/news/items/

- api_reference: endpoints-table row + a News Items section (limit
  clamp, no as_of, fail-closed 404, ETag/Last-Modified variance). Notes
  that its `score` is the editorial score, not the [-1,1] sentiment
  score of the same name under /api/signals/news/.
- project_structure: signals_views.py hosts both news endpoints now.
- pipeline design spec: SIGNALS_MAX_FILE_MB has a second reader.

Sphinx build clean (0 warnings).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: FlyM1ss

Docs/source/api_reference.rst

@@ -567,6 +567,9 @@ the signed ``fingpt_sessionid`` cookie. Callers may pass an optional
    * - GET
      - ``/api/signals/news/``
      - Latest news→sentiment signals artifact
+   * - GET
+     - ``/api/news/items/``
+     - Raw news stories from the newest Heartbeat batch
 
 All share the ``API_RATE_LIMIT`` budget (``429 {"error": "rate_limited"}``
 when exceeded). The chat endpoints can also return ``503 {"error": "busy"}``
@@ -723,6 +726,44 @@ an ``ETag`` validator and ``Cache-Control: public, max-age=300``.
 variants are ETag-only, so conditional requests for them must use
 ``If-None-Match``.
 
+News Items
+~~~~~~~~~~
+
+``GET /api/news/items/`` serves the **raw news stories** of the newest
+Heartbeat batch — the corpus the signals above are derived from, before any
+LLM scoring. Like ``/api/signals/news/`` it is an integration surface for
+external consumers; the browser extension does not call it.
+
+**Query parameters:**
+
+- ``limit=N`` — how many stories to return, newest first. Clamped to
+  ``[1, 200]``; defaults to ``50`` when absent. A non-integer value returns
+  ``400 {"error": "bad_limit"}``.
+
+There is no ``as_of`` here: this endpoint always reads the single newest
+batch.
+
+**Response (200):** ``{schema_version, items, count, batch}``, where ``batch``
+names the source file and each entry of ``items`` is
+``{guid, headline, url, source, published, description, tickers, score}``.
+``published`` is epoch seconds.
+
+.. note::
+
+   ``score`` on this endpoint is the pipeline's **editorial** score — how
+   newsworthy the story is, the gate that decides which stories become
+   sentiment candidates (``SIGNALS_MIN_EDITORIAL_SCORE``). It is *not* the
+   ``[-1, 1]`` sentiment score of the same name under ``/api/signals/news/``.
+   The two fields share a name and nothing else.
+
+``404 {"error": "no_items"}`` when no batch exists, or when the newest one is
+unreadable or validates to zero stories — the endpoint never falls back to an
+older batch, and never returns a ``500``. Responses carry an ``ETag`` and
+``Cache-Control: public, max-age=300``. ``Last-Modified`` is sent only on the
+default-limit variant — an explicit ``?limit`` slices the batch differently,
+so those variants are ETag-only and conditional requests for them must use
+``If-None-Match``.
+
 ---
 
 Usage Examples

Docs/source/project_structure.rst

@@ -38,7 +38,7 @@ Backend Structure
    ├── api/                          # REST API layer
    │   ├── views.py                  # Main API endpoints
    │   ├── openai_views.py           # OpenAI-compatible API endpoints
-   │   ├── signals_views.py          # News-signals endpoint (GET /api/signals/news/)
+   │   ├── signals_views.py          # News endpoints (GET /api/signals/news/, GET /api/news/items/)
    │   ├── middleware/               # CORS and custom middleware
    │   ├── utils/                    # API utility functions
    │   ├── apps.py                   # Django app configuration

Docs/superpowers/specs/2026-07-06-news-to-signals-pipeline-design.md

@@ -197,7 +197,7 @@ A machine-readable JSON Schema ships at `Heartbeat/schemas/signals-v1.schema.jso
 
 ## 5. Configuration (the v1 tuning surface)
 
-Env vars read by `news_signals.py` (module constants as defaults). This is the surface future user-facing tuning builds on:
+Env vars read by `news_signals.py` (module constants as defaults). This is the surface future user-facing tuning builds on. All are pipeline-only except `SIGNALS_MAX_FILE_MB`, which the Django API reads too (see its row):
 
 | Var | Default | Meaning |
 |-----|---------|---------|
@@ -209,7 +209,7 @@ Env vars read by `news_signals.py` (module constants as defaults). This is the s
 | `SIGNALS_THRESHOLD` | `0.20` | ± threshold for bullish/bearish label (40/60 band, empirically backed; was 0.15) |
 | `SIGNALS_DAMP_CAP` | `0.7` | Max \|score\| when under-corroborated |
 | `SIGNALS_DAMP_MIN_ARTICLES` | `2` | Corroboration needed for \|score\| > damp cap |
-| `SIGNALS_MAX_FILE_MB` | `10` | Reject oversized items files |
+| `SIGNALS_MAX_FILE_MB` | `10` | Reject oversized items files. **Two readers as of 2026-07-14:** `news_signals.py` (via `load_config`) and the Django API (via `settings.RAW_ITEMS_MAX_FILE_MB`, which `GET /api/news/items/` enforces when validating a batch). Deliberately one operator knob — raising it for the pipeline without raising it for the API would 404 a batch the pipeline happily accepted. Set it in `.env.production` alongside the heartbeat's own env file; the two defaults are pinned together by `Heartbeat/tests/test_port_parity.py`. |
 | `SIGNALS_STALENESS_ALERT_H` | `20` | Canary threshold (§6-C). Tuned, not arbitrary: the daily canary check runs 2 h after the daily beat, so a single fully-missed day leaves the newest artifact ~25.5 h old at the *next* day's check — a 30 h threshold would not cross that (it silently absorbs one entire missed day, only firing after a second consecutive miss); 20 h does. |
 
 ## 6. Failure policy (every mode decided)