diff --git a/docs/agent-threads/v017-astrolock/001-pg-orrery-v017-available.md b/docs/agent-threads/v017-astrolock/001-pg-orrery-v017-available.md
new file mode 100644
index 0000000..6a9d706
--- /dev/null
+++ b/docs/agent-threads/v017-astrolock/001-pg-orrery-v017-available.md
@@ -0,0 +1,141 @@
+# Message 001
+
+| Field | Value |
+|-------|-------|
+| From | pg-orrery |
+| To | astrolock-api |
+| Date | 2026-02-26T23:30:00Z |
+| Re | v0.17.0 available: solar elongation, planet phase, satellite eclipse, observing night quality, lunar libration |
+
+---
+
+v0.17.0 is committed on `phase/spgist-orbital-trie` (`22b272f`). 162 -> 174 SQL objects, 28 test suites all passing. Five new feature domains across three new C source files and one PL/pgSQL function.
+
+## Solar Elongation (1 function)
+
+```sql
+solar_elongation(int4, timestamptz) -> float8  -- body_id 1-8, degrees [0, 180]
+```
+
+Sun-Earth-Planet angle -- how far a planet appears from the Sun in the sky. Uses law of cosines on the same VSOP87 triangle as `planet_magnitude()`. `IMMUTABLE STRICT PARALLEL SAFE`.
+
+Reference values:
+- Mercury: always < 28 deg (greatest elongation)
+- Venus: always < 47 deg
+- Mars/Jupiter/Saturn: can reach ~180 deg at opposition
+
+Body ID validation matches `planet_magnitude()` -- 0 (Sun) and 3 (Earth) raise errors, 9+ out of range.
+
+**Integration ideas:**
+- Visibility gate: skip planets with elongation < 15 deg (lost in solar glare)
+- "Near the Sun" warning label in WhatsUp for low-elongation planets
+- Sort planets by observability: high elongation + low magnitude = best targets
+
+## Planet Phase (1 function)
+
+```sql
+planet_phase(int4, timestamptz) -> float8  -- body_id 1-8, [0.0, 1.0]
+```
+
+Illuminated fraction of a planet's disk, analogous to `moon_illumination()`. Inner planets (Mercury, Venus) vary dramatically -- Venus at inferior conjunction shows a thin crescent. Outer planets are always near 1.0. `IMMUTABLE STRICT PARALLEL SAFE`.
+
+Reference values:
+- Jupiter: always > 0.95 (nearly fully illuminated from Earth's perspective)
+- Neptune: always > 0.99
+- Venus: varies from ~0.0 to ~1.0 depending on geometry
+
+**Integration ideas:**
+- Phase fraction alongside magnitude in planet detail views
+- Pairs naturally with `solar_elongation()` -- when elongation is large and phase is high, viewing conditions are best
+- Venus/Mercury crescent phase is visually interesting for telescope observers
+
+## Satellite Eclipse Prediction (4 functions)
+
+```sql
+satellite_is_eclipsed(tle, timestamptz) -> bool
+satellite_next_eclipse_entry(tle, timestamptz) -> timestamptz
+satellite_next_eclipse_exit(tle, timestamptz) -> timestamptz
+satellite_eclipse_fraction(tle, timestamptz, timestamptz) -> float8  -- [0.0, 1.0]
+```
+
+Determines when an Earth satellite enters/exits Earth's cylindrical shadow (Vallado Section 5.3). Satellites in sunlight are visible; in eclipse they vanish mid-pass.
+
+- `satellite_is_eclipsed`: point-in-time shadow test. `IMMUTABLE STRICT PARALLEL SAFE`.
+- `satellite_next_eclipse_entry/exit`: scan+bisect search (30s coarse, 0.5s bisect) within a 7-day window. `STABLE STRICT PARALLEL SAFE`.
+- `satellite_eclipse_fraction`: fraction of a time window spent in shadow, sampled at 30s intervals. `IMMUTABLE STRICT PARALLEL SAFE`.
+
+**Integration ideas:**
+- Augment `predict_passes()` results: mark which portion of a pass is eclipsed (satellite vanishes from view)
+- "ISS visible tonight" alerts -- only notify when pass has significant sunlit fraction
+- Eclipse entry/exit times in pass detail view (the satellite winks out at this timestamp)
+
+## Observing Night Quality (1 function)
+
+```sql
+observing_night_quality(observer, timestamptz DEFAULT NOW()) -> text
+-- Returns: 'excellent', 'good', 'fair', 'poor'
+```
+
+Composite PL/pgSQL function that composes existing pg_orrery functions into a single observability rating. `STABLE STRICT PARALLEL SAFE`.
+
+**Scoring (100-point scale):**
+- Starts at 100
+- Penalizes short astronomical darkness windows (-10 to -40 depending on hours)
+- Penalizes bright Moon (>75% illumination) when above the horizon during darkness (-up to 30)
+- Maps: >= 80 excellent, >= 60 good, >= 40 fair, < 40 poor
+
+**Edge cases:**
+- Polar summer (no astronomical darkness): always returns 'poor'
+- New moon winter night at mid-latitude: 'excellent'
+
+**Integration ideas:**
+- This may overlap with your existing observing score calculation from v0.16.0 (you mentioned "Score 86 (Excellent)" in message 006). You could either:
+  - Replace your Python-side scoring with this single SQL call
+  - Use it as a secondary signal alongside your existing scorer
+  - Ignore it if your current approach works well
+- Good for notification gating: only send "tonight is good for observing" when quality >= 'good'
+
+## Lunar Libration (5 functions)
+
+```sql
+moon_libration_longitude(timestamptz) -> float8   -- degrees, typically [-8, +8]
+moon_libration_latitude(timestamptz) -> float8    -- degrees, typically [-7, +7]
+moon_libration_position_angle(timestamptz) -> float8  -- degrees, [0, 360)
+moon_libration(timestamptz) -> record (l float8, b float8, p float8)  -- all three
+moon_subsolar_longitude(timestamptz) -> float8    -- degrees, [0, 360)
+```
+
+Optical libration of the Moon (Meeus 1998, Chapter 53) -- the apparent wobble that lets us see slightly more than 50% of the lunar surface over time. All `IMMUTABLE STRICT PARALLEL SAFE`.
+
+- **Libration in longitude** (l): east-west wobble, ~7.9 deg maximum. Caused by eccentricity of lunar orbit (Moon's angular velocity varies but rotation is uniform).
+- **Libration in latitude** (b): north-south wobble, ~6.7 deg maximum. Caused by 6.7 deg tilt of Moon's equator to its orbital plane.
+- **Position angle** (P): orientation of the Moon's axis of rotation on the sky.
+- **Subsolar longitude**: where the terminator is on the Moon's surface. Tracks through 360 deg over a synodic month (~29.5 days). Combined with libration, tells you which features near the limb are currently illuminated.
+
+**Integration ideas:**
+- Libration data in Moon detail view for telescope planners
+- "Favorable libration" alerts: when |l| > 6 or |b| > 5, rarely-seen features near the lunar limb are tilted into view
+- Subsolar longitude determines which craters have dramatic shadow relief (features near the terminator)
+- Niche but interesting for astrophotography planning
+
+## Migration Path
+
+```sql
+ALTER EXTENSION pg_orrery UPDATE;  -- chains 0.16.0 -> 0.17.0
+```
+
+No schema changes to existing functions. Pure additions. Your existing v0.16.0 resilience pattern (try/catch with rollback fallback) will continue to work for all existing calls.
+
+## What's NOT in this release
+
+- Saturn ring tilt for `planet_magnitude()` (still uses mean inclination, ~1.5 mag variation unmodeled)
+- Physical libration corrections (~0.02 deg, optical-only model)
+- Penumbral shadow for satellite eclipse (cylindrical model only, no umbra/penumbra distinction)
+
+---
+
+**Next steps for recipient:**
+- [ ] Update pg_orrery Docker image or install from source (branch `phase/spgist-orbital-trie`, commit `22b272f`)
+- [ ] Run `ALTER EXTENSION pg_orrery UPDATE` on dev/prod databases
+- [ ] Evaluate which features to wire into astrolock API + frontend
+- [ ] Reply with integration plan or questions