← AstroMatrix Reports — all pages
Chart Journey Brief
 Developer brief · 2026-10-21 · register FEATURE-38, FEATURE-44
Chart Journey Brief
The poll winners mostly ask for things AstroMatrix already has. What's missing is a journey through them: an order, the connections between placements, and a reason why an item matters. This brief scopes the release and the small Flutter package Mark approved. Nothing here is built yet.
Mark's decisions and order
Revised 2026-10-21 after Mark's review. The Chart Journey direction is approved. The 11.1.9 release is not yet authorised. 11.1.9 is decided separately and is not held for Chart Journey work.
 | # | Work | Decision
 | 1 | 11.1.9: reconcile the missing What Matters Now fix, run regressions | Do now No release without Mark's approval.
 | 2 | Real reading-open measurement, on the device | Required Before any Chart Journey result is read.
 | 3 | Guided walkthrough and meaningful Connected Patterns | Build together Proven on real charts before the design counts as proven.
 | 4 | One ranking rule and its reasons, on Daily and in the Matrix | Build
 | 5 | Editable reflection questions | Build Safeguards checked first.
 | 6 | Retrograde navigation | Small fix Independent of the rest.
 | 7 | Friend invitations | Investigate and design first
 | 8 | Generic learning platform or chatbot | Don't build
Success is people coming back on another day to discover something more about their own chart. Finishing a walkthrough, or tapping Next, is not success. The walkthrough's value depends on the quality of its connections, not on its navigation.
The unmet need: what users say, and what the journal shows
Hypothesis, revised 2026-10-23. The original premise, that people know astrology but don't connect it to their lives, is not established and is no longer treated as fact. What the evidence supports is narrower: people can reach personalised astrology through AstroMatrix, and some want help with three separate things. Synthesis: how the pieces fit together. Explanation: why something means what it means, which is an education problem. Application: what it means for their life now, which is the closest match to the original dilemma. The journal shows people rarely write about that connection. It doesn't show that they don't make it. Missing: whether ordinary Matrix users, not Discord members, already get these insights, and what they feel is missing. Open question: is "guided self-discovery" about finding out more about yourself, or about understanding and using what AstroMatrix already tells you?
Added 2026-10-23. Evidence only, no proposals. Discord: the 47 people who voted for a learning or self-discovery option, and everything they have posted publicly. Journal: aggregate behaviour only; no journal text was read, only lengths and dates.
1. What "guided self-discovery" and "lessons on your own chart" mean, in voters' own words
28 of the 47 voters have posted somewhere (918 messages); 19 never have. The follow-up post asking "Learn Your Birth Chart" voters what they meant got no replies, even though members can post in #whats-new. Their messages point to three different asks:
 | Ask | Their words
 | Synthesis: how placements work together | Wants to learn how all their placements work together, which they feel the app is missing; they can research each placement separately but not how they combine. This voter chose all five learning options.
 | Explanation: terms and features | "What does detriment mean?" · "idek how to identify a conjunct or sextile by eye yet" · "I don't understand the astrocartography at all" · "the lines run through these cities but what do I do with that information" · "isn't enough explanations in-app" · "Is there a way to have a video or something to explain it better?" · one learner describes moving from basics to houses to aspects.
 | Application: what this means for me now | Asking what a current transit to their natal Sun means and how to navigate it (a Guided Self-Discovery voter) · asking how to work with a difficult placement · reading their own and a partner's charts to understand the relationship.
Also notable: voters learn largely from books (repeated recommendations and a request for a shared book list). Practitioners are sceptical of AI chart readings ("They'll say things square… when they don't", "using AI in general is just bad"); one voter prefers talking to their own AI over writing in a journal. Caveat: these are about 20 voices, and two members are heavily represented.
2. Does the app's own reflection mechanism show private connection?
 | Measure | Result
 | People who wrote any reflection, last 28 days | 978, about 1.2% of 80,915 active users (GA4)
 | Prompted vs voluntary | 961 wrote only in answer to a reflection prompt; 12 only voluntarily; 5 both. Voluntary notes on saved readings: 18 in 28 days.
 | Saving without writing | Common: about 14,800 readings saved by about 4,100 people, plus about 31,000 saved reports, in 28 days
 | Repeat reflection, since prompts launched 9/13 | 966 writers, 1,664 entries: 807 (84%) wrote on one day only, 159 (16%) on 2+ days, 11 on 6+ days
 | Length | 310 under 20 characters, 444 of 20–59, 509 of 60–149, 333 of 150–399, 68 of 400+
 | What prompts are about | Transit aspects 70%, forecasts 13%, natal aspects and signs 14%, progressed 3%
 | Trend | About 480 entries a week from about 340 people in the two weeks after launch, then about 270 from about 175 in the last two weeks
 | Opening the journal, last 28 days | 11,213 users opened it (about 14% of active users); 2,658 on 2+ days, 471 on 4+ days
Limits: journal opens use a different user ID from journal entries, so they can't be linked to writers. Returning to the reading a reflection was written on isn't measured. 704 prompt entries carry no user ID and are excluded. Writing is evidence of use, not of insight, and someone who never writes may still find personal meaning.
Assessment
The people asking for guidance are not asking for more readings. In their words they want three things the reading-by-reading experience doesn't obviously give them: how their placements fit together, plain explanations of terms and features, and help applying a reading to what's happening to them now.
Private reflection in the app is real but small. About 1 in 80 active users wrote a reflection in 28 days, almost always because a prompt asked, usually once, usually briefly, and mostly about current transits. Voluntary journaling on readings is close to zero.
What most people do instead is keep readings. Saving readings and reports is roughly 15 times more common than writing about them. That shows readings are valued enough to keep; it doesn't show what people do with them afterwards.
The existing product may already meet part of the need, especially for confident users who read and save. The evidence doesn't show it meeting the synthesis, explanation and application asks above.
Matrix audit
Audited 2026-10-23 against the live build (11.1.8, 5f59ca35), the report server (routes/ai.js), and 28 days of Matrix reports (reportGenerations, read-only, provisional). This section replaces versions 4 and 5 of the Matrix analysis, which read a report field that merges several dropdown options. Proposals are withdrawn until this audit is reviewed.
How the screen works
Tabs are life areas. Self: Summary, Purpose, Harmony, Love, Abundance, Evolution. Relationship: Chemistry, Support, Connection, Evolution.
Each tab is a radar chart followed by three sub-area panels stacked vertically (e.g. Purpose: Path & Career, Ambition & Drive, Vision & Awareness). Each panel lists all of its items and has its own Report button. To reach the second or third sub-area you scroll past the whole first list (matrix.dart:1650-1700).
One dropdown, titled "Report", holds 7 options on the self Matrix and 3 on a relationship Matrix. It filters what the whole Matrix shows and sets what the next report covers, and the app remembers the choice (saveCategory).
 | Dropdown option | What it shows (matrix_service.dart) | Sent to server as | Self reports, 28 days
 | All Aspects (default) | Everything: birth, all transit types, progressed, draconic. No filter. | all | ~864 (21%), 376 profiles*
 | Foundation (Birth) | Birth chart only | foundation | 1,473 (36%), 505
 | All Transits | Weekly + monthly + progressed | all | ~1,175 (29%), 501*
 | Weekly (Transits) | Fast-planet transits | weekly | 228 (6%), 76
 | Monthly (Transits) | Slow-planet transits | monthly | 121 (3%), 49
 | Growth (Progressed) | Progressed chart | progressed | 96 (2%), 48
 | Soul (Draconic) | Draconic chart; hidden without a birth time | draconic | 141 (3%), 65
 | Relationship: All Aspects, Connection (Synastry), Unity (Composite) | Synastry, composite, or both | all for all three | 2,833 total; can't be split
* All Aspects and All Transits are both sent as all, so I separated them by contents. A report containing any birth placement counts as All Aspects; one with only transit or progressed items counts as All Transits. An All Aspects report on a sub-area where the person has no birth placements would be miscounted as All Transits. Total self reports: 4,100.
What the numbers show, and don't
People do choose the option. The default, All Aspects, produced only 21% of self reports. Birth (36%) and All Transits (29%) were picked more often. Since the last deploy, explicit picks in the app number 276 (matrix_lens_selected: All Aspects 58, Weekly 52, All Transits 52, Birth 49, Monthly 29, Progressed 22, Draconic 14).
Timing is used. About 40% of self reports come from a timing option (All Transits, Weekly, Monthly, Progressed). Version 4's "5%" and version 5's "98% blended" were both wrong, because both read all as one option.
Within a tab, the first sub-area leads (Path & Career 1,162 against 217 and 162; Physical Attraction 715; Security & Roots 222, and so on). The layout explains how that could happen, since the first panel is the only one visible without scrolling past a list. It doesn't prove people would choose differently. A rotation test is the only way to tell.
Return isn't measured. Only 9% of profiles generated a report on more than one day, but that counts new reports, not people coming back to read.
Relationship options can't be told apart in the data, because all three send the same value.
Report instructions: checked, not a defect
The server's generic "birth chart + transits" wording for timing options was checked against 9 saved reports (All Transits, Weekly, Monthly, Progressed, Draconic) and their exact inputs. None invented birth-chart content. Two reports did misstate whether a transit had begun. That traces to a separate, already-known cause: percentComplete arrives as 0 on transit aspects. Another session is handling it under ISSUE-137, not this brief.
The objective: make the astrology people already know useful to them
Added 2026-10-23 from the Discord conversation study. The goal is not to teach more astrology or produce more interpretation. It is to help people connect the astrology they already know to their own lives.
What Discord shows
The vocabulary is there. About 35% of 1,782 member messages since 9/23 are astrology talk with nothing personal. 228 of 371 introductions are big-three listings.
The personal reflection is there too. 60% of messages have no astrology in them, including long, open conversations about exes, family and feeling misunderstood.
The two rarely meet. About 5–10% of messages connect them. Only 34 of the 138 astrology-speaking members do it even once, and two members wrote 30 of the 89 messages that do.
People may well make the connection privately, or choose not to post it. Discord shows what people say in public, not what they think.
How the members who connect it do it
Through timing: a life event tied to a profection year, a Saturn or Chiron return, or a retrograde moving through a house (for example, a health event during a Saturn return).
Through other people: a mother, an ex or a "situationship" comes first, and their chart is where the person goes looking.
By testing readings against their life: they keep the reading or house system that fits (when a reading matches their life closely).
By asking what to do (asking how to work with a difficult placement).
By empathy through shared placements (members bonding over a shared placement).
What this changes in the package
Two directions, not one. Chart → Life: the walkthrough and Connected Patterns turn a placement into a question about the person's experience. Life → Chart: start from something they care about now, such as home and family, a relationship, work, health or a loss. Then show what in their chart and current timing speaks to it: the transits and returns active in the matching houses now, or the comparison with the other person. Both pieces already exist (the Matrix's transits by house, and synastry). Life → Chart may matter more, because it starts where the person already is.
Ask "does this fit you?" on walkthrough steps, connection lines and Life → Chart results. A yes is the clearest signal we can get that a reading meant something personally, and it mirrors what the connected members already do.
Lead with timing. Returns, profections and transits through houses are where people's life stories attach. This depends on ISSUE-783 (every retrograde pass, correct exact dates).
Include "what to do" where a reading names a difficulty.
Handle heavy subjects with care. Several of these stories involve death, pregnancy loss, disability and trauma. Free-text Life → Chart input needs the same distress handling as AI reports (ISSUE-722).
The measure, revised
Unique users who make a personal connection with their chart (answer "this fits me" on a reading or connection, or start from a life area and open what it leads to), and whether those users come back on another day. Engagement with Chart Journey screens by itself is not the measure.
Discord prompts: the daily moon post asks "Anyone feeling that today?" and has had no replies so far. Treat that as an early signal, not a verdict. A concrete, chart-specific prompt may do better, and some people will reflect privately in the app but not in public.
What the polls asked for, against what users see today
Live build: 11.1.8, build 300100101 (production app-open counts, 2026-10-21: 3,526 iOS and 3,091 Android opens, against about 1,160 still on 11.1.7). "Branch-only" means the code exists but isn't in that build.
 | Poll ask (votes) | What exists | Class | Smallest change
 | Guided self-discovery (17/46), guided walkthrough (11/29) | No ordered path through the chart. The reading screen already has Back/Next, but only steps through whatever list it was opened from (component_summary.dart:3425-3468). | Genuinely missing | Walkthrough, package item 1
 | Lessons on your own chart (20/64), learn your birth chart (9/25) | One reading per placement, opened often. Each placement reads on its own, and the text is the same for everyone with that placement: routes/component.js:1580 reads uid and never uses it. Only the AI Matrix report combines placements. Connected Patterns is branch-only (11.1.9). | Poorly connected | Ship Connected Patterns with relationship lines (item 2), and link each placement to the Foundation report
 | Visual mini-lessons (22/64) | The Guide is generic reference with no menu entry; users reach it only through search or word links. The concept boxes under a reading don't say why to tap them. | Incomplete | A visible "Learn" entry, and a one-line "why this matters" on each concept box. Not in this package.
 | Ask Your Chart (the chatbot came last, 4/46) | The tarot question box takes free text but sends no chart data. "Report on this" on each placement uses a fixed reflection question (component_summary.dart:1108). | Poorly connected | Editable question, item 4
 | Friends & family (8/27) | A Friends system is live (since 11.1.7): handle search, requests, chat, Share Profile, and a friend as the second chart. 37 friend links accepted, ever. 32% of accounts hold 2+ people, and comparing with them works. | Incomplete | An invite for someone not yet on the app. Design task.
 | Retrogrades (11/27) | Daily panel about 10 sections down, generic (planet and sign only), and its "See more" opens the Forecasts tab (home_screen.dart:1348). | Poorly connected | Retrograde fix, item 5
 | "Which of this matters to me?" (advisor's hypothesis) | What Matters Now ranks a top 3 by importanceScore and never says why. About 45 items on Daily. About 170 transits in the Matrix, sorted another way. | Incomplete | Ranking reasons, item 3
11.1.9 release scope
Candidate 15488952 on release/11.1.9: 47 commits on top of the live build 5f59ca35. 5 opens on 11.1.9 so far, from test devices.
What ships
Connected Patterns (FEATURE-52), including one-time refetches of placements cached before affinity data and before ISSUE-751
Chart export to PDF (FEATURE-58)
Important Birth Aspects panel and birth-aspect ranking on Daily (FEATURE-26)
Shortcut-tap measurement; Void of Course removed from Daily (FEATURE-11, FEATURE-26)
Android checkout hardening (ISSUE-696, 697, 699)
iOS widget timezone fixes (ISSUE-385)
Campaign sendId forwarding (ISSUE-745)
Fixes: i18n saved-language repair (ISSUE-759), journal refused edits (ISSUE-392), navigation back (ISSUE-420), matrix aspect settings (ISSUE-750), support chat, tarot accessibility
What does not ship
The daily-changing What Matters Now (df74ec43). It's only on birth-issues and feature/auth-token. It was part of the agreed scope, so either merge it in and test it, or remove it from the scope explicitly. It should apply cleanly: it touches only lib/services/forecast_service.dart and its test, and 11.1.9 hasn't changed either file since they diverged. This was checked by reading the history; the merge itself hasn't been run.
The critical-degree text fix (e6e9b180, ISSUE-767), the commit just before it on the same branch, is also absent. It touches different files, so df74ec43 doesn't depend on it. Decide whether it belongs in 11.1.9 too.
Connected Patterns in 11.1.9 shows a list of names under one generic line ("These placements express related themes in your chart."). It doesn't yet explain any relationship (item 3).
To reconcile, in the Flutter repo
git checkout release/11.1.9
git cherry-pick df74ec43
flutter test
# bump the build to 11.1.9+300100104 before uploading:
# 300100103 is already installed on test devices
Server dependencies, checked live
AffinityCandidates is served on GetComponent (23 candidates for Moon in Scorpio)
/affiliate/a/t/:sendId returns 302; an unknown ID falls through to the normal link
Release risks and regression checks
Unit tests: 233 test files in test/. Flutter isn't installed on the server-side machine, so whoever cuts the build runs flutter test on 15488952.
Billing (highest risk): on Android, check a purchase, a double tap on buy, and a restore with stale product details. A regression here costs revenue directly.
One-time refetches: two "refetch once" migrations re-request placements cached before affinity data. Expect a burst of GetComponent traffic as users update. Watch the component server's timeouts after the release.
Language repair (ISSUE-759) rewrites a stored setting once. Test an upgrade from a pre-9.8.5 install with a non-English language.
iOS widgets: check Moon and planetary-hour widgets in a timezone far from GMT.
PDF export: check who may export, and a saved report's chart printing.
Flutter work package
Numbered in Mark's order. The work is Flutter unless marked Node.
2. Measure real reading opens, on the deviceRequired first
 WhyThe app caches readings, so the server never sees a repeat open. Server-side counts of GetComponent, including component_views, can't measure reading or return, and none of the success measures below may use them.
 ScopeThe app already counts every reading open, cached ones included, in _loadComponentData (component_summary.dart:492, component_opened_total). But that counter is anonymous and only labelled by category. Next to it, send one event per open carrying the account, the reading (category and name), the local date, and where it was opened from (walkthrough, Connected Patterns, Matrix, Daily, chart wheel, search).
 NodeAn endpoint that stores one row per account, reading and day (repeats on the same day collapse), plus a read-only report: of the accounts that opened a reading through the walkthrough or Connected Patterns, what share opened a natal reading again on a different day within 14 days, compared with accounts that didn't. I can build this part.
 Risk_loadComponentData also re-runs on reloads, so de-duplication per day is what keeps the numbers honest. The data is account-linked and has to be covered by the account-deletion path.
3. Guided walkthrough and meaningful Connected Patterns, built togetherBuild together
 What it isAs specified, this is a sequence of readings, not yet a guided learning journey. Its value rests entirely on the connection lines. Both features share one piece: a line that says how two placements in this person's chart relate.
 Connection lineFor two placements, say whether they reinforce each other (conjunction, trine or sextile between the two planets in this chart), are in tension (square or opposition), or share a theme, naming it. Today each affinity candidate carries only Component, Category, Score and Route (house or aspect), with no theme or relationship. Aspect type is available on the device. Shared themes need a small Node change returning the traits two placements have in common, from the trait lists components already carry. With no real relationship, show no line rather than filler.
 WalkthroughSun, Moon, Rising, then the 3–5 strongest natal aspects (the FEATURE-26 ranking in 11.1.9), at most about 8 steps, on the existing reading screen. Each step shows why it matters (written per step type, translated) and its connection line to the previous step.
 Connected PatternsThe same connection line under each match. The version in 11.1.9 has none; it can ship as a first step but proves nothing yet.
 Acceptance testBefore the design counts as proven, run it on at least 5 real natal charts of different shapes (for example a stellium, a chart with a dominant square, a chart with few major aspects, a late-degree Rising, and a chart with no birth time). A person who reads astrology checks each output against four points:
Every connection line names both placements, and its aspect is correct for that chart.
No two lines in one walkthrough say the same thing.
At least one tension and one reinforcement appear where the chart has them.
After the walkthrough, the reader can state the chart's story in 2–3 sentences that wouldn't fit a different chart.
 A chart that reads as eight isolated readings with captions fails.
 MeasureReturn on another day (item 2), comparing people who used the walkthrough or Connected Patterns with those who didn't. Steps reached is a diagnostic, not the outcome.
4. One ranking rule for Daily and the Matrix, with reasonsBuild
 The ruleDefine one shared function that both screens call, so they can't drift apart. If df74ec43 ships, What Matters Now is no longer a pure score order: slot 1 is the biggest active transit, and the rest are significant transits that are exact or begin today. Write the rule down first, then use it in both places. Today the Matrix sorts by distance of percentComplete from 50, which is 0 on every transit-aspect row.
 ReasonsOne line per item from the terms that ranked it, for example "Slow planet · hard aspect · your Sun · exact today".
 RolloutShip the reasons and the shared Matrix sort together. If the reasons go first, they appear on Daily only, with wording that doesn't suggest the Matrix uses the same ranking.
 RiskRe-sorting the Matrix changes a screen every user knows.
 MeasureTaps on What Matters Now items per Daily open, and the return outcome.
5. Editable reflection questionsBuild, safeguards checked
 Scope"Report on this" (component_summary.dart:1108) becomes a text field pre-filled with the reflection question, which the user can edit before sending. The server already accepts specificQuestion (routes/ai.js:809).
 Depends onThe report path's existing usage limit and paywall apply unchanged.
 RiskFree text reaches the AI. The report distress check (ISSUE-722) must see the user's question, not only the prompt. Confirm before release.
 MeasureShare of reports sent with an edited question. Store the question with the report so it can be read later.
6. Retrograde navigation fixSmall independent fix
 ScopePoint the Daily panel's "See more" at /calendars?Tab=Retrogrades (it goes to Forecasts today, home_screen.dart:1348), and move the panel up into Today's Sky.
 Not yetPersonal retrogrades (a retrograde planet over your natal points) wait on ISSUE-783. The engine currently returns only the first pass of a multi-pass transit. A Discord user hit this on 2026-10-01.
7. Friend invitesInvestigate and design first
 Start withWhy 37 accepted friendships in four months? Is it the entry point (behind the Users screen), the "Love Match" label, or the requirement that both people already have accounts? Then design invite → install → friend request → comparison, with attribution and a path for someone who already has the app.
About the usage numbers
component_views holds a lifetime counter per placement since 2026-09-26, with no user and no dates. Because the app caches readings, it counts first-time fetches, not reads. The earlier figure of about 244k natal reading views shows consumption, roughly, and nothing about understanding or return. The first version of this brief proposed measuring return through GetComponent; that couldn't work for the same caching reason, and it is replaced by item 2.
Corrections to earlier analysis
FEATURE-ANALYSIS (2026-10-16) treated the social layer as unbuilt. A Friends system is live; it's hard to find, has no invite step and isn't measured.
Its "release 11.1.8" step is done: 11.1.8 is the live build.
The deleted 2026-10-16 learning audit called readings "genuinely personal". They aren't personalised per user.
Usage counts in this brief are from read-only database reads, not the canonical metrics script. Treat them as provisional.
 Register: FEATURE-38 (learning path), FEATURE-44 (sharing and friends), FEATURE-52 (Connected Patterns), FEATURE-11 (What Matters Now), ISSUE-783 (multi-pass transits).
 Sources: Flutter release/11.1.9 at 15488952 and the live build 5f59ca35; Node origin/master; production metrics and responses read 2026-10-21.