@troylar/sightline 0.0.0-stage → 1.120.3

package/docs/images/roadmap-map-light.svg

@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 640" role="img" aria-labelledby="title desc"><title id="title">Sightline: get your arms around a big roadmap</title><desc id="desc">Illustrative planning map: rough requests connect to Integrations, Search and Platform workstreams. Dependencies and a shared specialist lead to scope, sequencing and capacity decisions. This is a conceptual diagram, not an app screenshot.</desc>
+<style>text{font-family:"Avenir Next","Trebuchet MS",Arial,sans-serif}</style>
+<rect x="0" y="0" width="1280" height="640" rx="24" fill="#f5f8fc"/>
+<text x="44" y="86" fill="#172b4d" font-size="58" font-weight="650" text-anchor="start">A big roadmap.</text>
+<text x="44" y="156" fill="#172b4d" font-size="58" font-weight="650" text-anchor="start">A clearer way through.</text>
+<text x="790" y="80" fill="#536783" font-size="23" font-weight="500" text-anchor="start">Many teams. Competing requests.</text>
+<text x="790" y="114" fill="#536783" font-size="23" font-weight="500" text-anchor="start">Dependencies. Limited capacity.</text>
+<text x="46" y="218" fill="#536783" font-size="24" font-weight="500" text-anchor="start">Plan together. Think with AI. Review the changes.</text>
+<path d="M44 252 H1236" fill="none" stroke="#d6e1f0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<text x="46" y="306" fill="#536783" font-size="21" font-weight="600" text-anchor="start">The rough input</text>
+<rect x="46" y="344" width="214" height="44" rx="6" fill="#ffffff" stroke="#d6e1f0"/>
+<text x="63" y="373" fill="#172b4d" font-size="20" font-weight="500" text-anchor="start">Meeting notes</text>
+<path d="M260 366 H288 Q308 366 308 426" fill="none" stroke="#d6e1f0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="46" y="404" width="214" height="44" rx="6" fill="#ffffff" stroke="#d6e1f0"/>
+<text x="63" y="433" fill="#172b4d" font-size="20" font-weight="500" text-anchor="start">Jira work</text>
+<path d="M260 426 H288 Q308 426 308 426" fill="none" stroke="#d6e1f0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="46" y="464" width="214" height="44" rx="6" fill="#ffffff" stroke="#d6e1f0"/>
+<text x="63" y="493" fill="#172b4d" font-size="20" font-weight="500" text-anchor="start">New requests</text>
+<path d="M260 486 H288 Q308 486 308 426" fill="none" stroke="#d6e1f0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<circle cx="308" cy="426" r="6" fill="#2563eb"/>
+<path d="M308 426 H338" fill="none" stroke="#2563eb" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+<text x="350" y="306" fill="#172b4d" font-size="24" font-weight="650" text-anchor="start">One shared plan</text>
+<path d="M350 374 H885" fill="none" stroke="#2563eb" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+<text x="350" y="340" fill="#2563eb" font-size="18" font-weight="650" text-anchor="start">Integrations</text>
+<rect x="374" y="360" width="205" height="36" rx="7" fill="#edf3ff"/>
+<text x="388" y="385" fill="#2563eb" font-size="18" font-weight="600" text-anchor="start">Customer context</text>
+<circle cx="878" cy="374" r="7" fill="#f5f8fc" stroke="#2563eb" stroke-width="3"/>
+<path d="M350 446 H885" fill="none" stroke="#08736c" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+<text x="350" y="412" fill="#08736c" font-size="18" font-weight="650" text-anchor="start">Search</text>
+<rect x="563" y="432" width="177" height="36" rx="7" fill="#e2f4f0"/>
+<text x="577" y="457" fill="#08736c" font-size="18" font-weight="600" text-anchor="start">Search quality</text>
+<circle cx="878" cy="446" r="7" fill="#f5f8fc" stroke="#08736c" stroke-width="3"/>
+<path d="M350 518 H885" fill="none" stroke="#7447ba" stroke-width="4" stroke-linecap="round" stroke-linejoin="round"/>
+<text x="350" y="484" fill="#7447ba" font-size="18" font-weight="650" text-anchor="start">Platform</text>
+<rect x="407" y="504" width="184" height="36" rx="7" fill="#eee8f8"/>
+<text x="421" y="529" fill="#7447ba" font-size="18" font-weight="600" text-anchor="start">Index migration</text>
+<circle cx="878" cy="518" r="7" fill="#f5f8fc" stroke="#7447ba" stroke-width="3"/>
+<path d="M592 522 H620 Q643 522 643 500 V484 Q643 466 663 466 H696 V448" fill="none" stroke="#7447ba" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="6 8"/>
+<circle cx="643" cy="487" r="13" fill="#f5f8fc" stroke="#91600a" stroke-width="3"/>
+<text x="666" y="491" fill="#91600a" font-size="17" font-weight="600" text-anchor="start">shared specialist</text>
+<path d="M891 374 H922 Q942 374 942 402 V462 Q942 482 962 482" fill="none" stroke="#d6e1f0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M891 446 H942" fill="none" stroke="#d6e1f0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M891 518 H923 Q942 518 942 498 V482" fill="none" stroke="#d6e1f0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<text x="980" y="351" fill="#172b4d" font-size="25" font-weight="650" text-anchor="start">What needs</text>
+<text x="980" y="384" fill="#172b4d" font-size="25" font-weight="650" text-anchor="start">a decision?</text>
+<circle cx="990" cy="422" r="5" fill="#2563eb"/>
+<text x="1008" y="428" fill="#172b4d" font-size="19" font-weight="500" text-anchor="start">Scope overlap</text>
+<circle cx="990" cy="466" r="5" fill="#7447ba"/>
+<text x="1008" y="472" fill="#172b4d" font-size="19" font-weight="500" text-anchor="start">Shared capacity</text>
+<circle cx="990" cy="510" r="5" fill="#08736c"/>
+<text x="1008" y="516" fill="#172b4d" font-size="19" font-weight="500" text-anchor="start">What fits next</text>
+<text x="46" y="605" fill="#536783" font-size="18" font-weight="500" text-anchor="start">Illustrative planning map. Your plan and your assistant supply the real context.</text>
+</svg>

package/docs/images/roadmap-map-mobile-dark.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 760" role="img" aria-labelledby="title desc"><title id="title">Sightline: a clearer way through a big roadmap</title><desc id="desc">Illustrative planning map: notes, Jira work and requests connect to three workstreams. See their dependencies and find the next decision. Not an app screenshot.</desc>
+<style>text{font-family:"Avenir Next","Trebuchet MS",Arial,sans-serif}</style>
+<rect x="0" y="0" width="520" height="760" rx="24" fill="#101b30"/>
+<text x="28" y="68" fill="#eef4ff" font-size="45" font-weight="650" text-anchor="start">A big roadmap.</text>
+<text x="28" y="123" fill="#eef4ff" font-size="45" font-weight="650" text-anchor="start">A clearer way</text>
+<text x="28" y="178" fill="#eef4ff" font-size="45" font-weight="650" text-anchor="start">through.</text>
+<text x="30" y="242" fill="#b0c1dd" font-size="22" font-weight="500" text-anchor="start">Plan together. Think with AI.</text>
+<text x="30" y="272" fill="#b0c1dd" font-size="22" font-weight="500" text-anchor="start">Review the changes.</text>
+<path d="M28 302 H492" fill="none" stroke="#314767" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="28" y="330" width="134" height="44" rx="6" fill="#192943" stroke="#314767"/>
+<text x="95" y="359" fill="#eef4ff" font-size="19" font-weight="500" text-anchor="middle">Notes</text>
+<path d="M95 374 V394 Q95 414 260 414" fill="none" stroke="#314767" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="193" y="330" width="134" height="44" rx="6" fill="#192943" stroke="#314767"/>
+<text x="260" y="359" fill="#eef4ff" font-size="19" font-weight="500" text-anchor="middle">Jira work</text>
+<path d="M260 374 V394 Q260 414 260 414" fill="none" stroke="#314767" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="358" y="330" width="134" height="44" rx="6" fill="#192943" stroke="#314767"/>
+<text x="425" y="359" fill="#eef4ff" font-size="19" font-weight="500" text-anchor="middle">Requests</text>
+<path d="M425 374 V394 Q425 414 260 414" fill="none" stroke="#314767" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<circle cx="260" cy="414" r="6" fill="#80adff"/>
+<path d="M260 414 V458 H470" fill="none" stroke="#80adff" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M260 414 V526 H470" fill="none" stroke="#62d5c7" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M260 414 V594 H470" fill="none" stroke="#c1a2ff" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="28" y="435" width="464" height="48" rx="7" fill="#203c68"/>
+<text x="44" y="465" fill="#80adff" font-size="20" font-weight="650" text-anchor="start">Integrations</text>
+<text x="234" y="465" fill="#eef4ff" font-size="19" font-weight="500" text-anchor="start">Customer context</text>
+<rect x="28" y="503" width="464" height="48" rx="7" fill="#183f42"/>
+<text x="44" y="533" fill="#62d5c7" font-size="20" font-weight="650" text-anchor="start">Search</text>
+<text x="234" y="533" fill="#eef4ff" font-size="19" font-weight="500" text-anchor="start">Search quality</text>
+<rect x="28" y="571" width="464" height="48" rx="7" fill="#362e53"/>
+<text x="44" y="601" fill="#c1a2ff" font-size="20" font-weight="650" text-anchor="start">Platform</text>
+<text x="234" y="601" fill="#eef4ff" font-size="19" font-weight="500" text-anchor="start">Index migration</text>
+<path d="M218 594 H205 V526 H218" fill="none" stroke="#c1a2ff" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="6 8"/>
+<circle cx="205" cy="560" r="9" fill="#101b30" stroke="#f6c36a" stroke-width="3"/>
+<text x="30" y="678" fill="#eef4ff" font-size="27" font-weight="650" text-anchor="start">See the dependencies.</text>
+<text x="30" y="712" fill="#eef4ff" font-size="27" font-weight="650" text-anchor="start">Find the next decision.</text>
+<text x="30" y="741" fill="#b0c1dd" font-size="17" font-weight="500" text-anchor="start">Illustrative planning map</text>
+</svg>

package/docs/images/roadmap-map-mobile-light.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 520 760" role="img" aria-labelledby="title desc"><title id="title">Sightline: a clearer way through a big roadmap</title><desc id="desc">Illustrative planning map: notes, Jira work and requests connect to three workstreams. See their dependencies and find the next decision. Not an app screenshot.</desc>
+<style>text{font-family:"Avenir Next","Trebuchet MS",Arial,sans-serif}</style>
+<rect x="0" y="0" width="520" height="760" rx="24" fill="#f5f8fc"/>
+<text x="28" y="68" fill="#172b4d" font-size="45" font-weight="650" text-anchor="start">A big roadmap.</text>
+<text x="28" y="123" fill="#172b4d" font-size="45" font-weight="650" text-anchor="start">A clearer way</text>
+<text x="28" y="178" fill="#172b4d" font-size="45" font-weight="650" text-anchor="start">through.</text>
+<text x="30" y="242" fill="#536783" font-size="22" font-weight="500" text-anchor="start">Plan together. Think with AI.</text>
+<text x="30" y="272" fill="#536783" font-size="22" font-weight="500" text-anchor="start">Review the changes.</text>
+<path d="M28 302 H492" fill="none" stroke="#d6e1f0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="28" y="330" width="134" height="44" rx="6" fill="#ffffff" stroke="#d6e1f0"/>
+<text x="95" y="359" fill="#172b4d" font-size="19" font-weight="500" text-anchor="middle">Notes</text>
+<path d="M95 374 V394 Q95 414 260 414" fill="none" stroke="#d6e1f0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="193" y="330" width="134" height="44" rx="6" fill="#ffffff" stroke="#d6e1f0"/>
+<text x="260" y="359" fill="#172b4d" font-size="19" font-weight="500" text-anchor="middle">Jira work</text>
+<path d="M260 374 V394 Q260 414 260 414" fill="none" stroke="#d6e1f0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="358" y="330" width="134" height="44" rx="6" fill="#ffffff" stroke="#d6e1f0"/>
+<text x="425" y="359" fill="#172b4d" font-size="19" font-weight="500" text-anchor="middle">Requests</text>
+<path d="M425 374 V394 Q425 414 260 414" fill="none" stroke="#d6e1f0" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<circle cx="260" cy="414" r="6" fill="#2563eb"/>
+<path d="M260 414 V458 H470" fill="none" stroke="#2563eb" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M260 414 V526 H470" fill="none" stroke="#08736c" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M260 414 V594 H470" fill="none" stroke="#7447ba" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+<rect x="28" y="435" width="464" height="48" rx="7" fill="#edf3ff"/>
+<text x="44" y="465" fill="#2563eb" font-size="20" font-weight="650" text-anchor="start">Integrations</text>
+<text x="234" y="465" fill="#172b4d" font-size="19" font-weight="500" text-anchor="start">Customer context</text>
+<rect x="28" y="503" width="464" height="48" rx="7" fill="#e2f4f0"/>
+<text x="44" y="533" fill="#08736c" font-size="20" font-weight="650" text-anchor="start">Search</text>
+<text x="234" y="533" fill="#172b4d" font-size="19" font-weight="500" text-anchor="start">Search quality</text>
+<rect x="28" y="571" width="464" height="48" rx="7" fill="#eee8f8"/>
+<text x="44" y="601" fill="#7447ba" font-size="20" font-weight="650" text-anchor="start">Platform</text>
+<text x="234" y="601" fill="#172b4d" font-size="19" font-weight="500" text-anchor="start">Index migration</text>
+<path d="M218 594 H205 V526 H218" fill="none" stroke="#7447ba" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="6 8"/>
+<circle cx="205" cy="560" r="9" fill="#f5f8fc" stroke="#91600a" stroke-width="3"/>
+<text x="30" y="678" fill="#172b4d" font-size="27" font-weight="650" text-anchor="start">See the dependencies.</text>
+<text x="30" y="712" fill="#172b4d" font-size="27" font-weight="650" text-anchor="start">Find the next decision.</text>
+<text x="30" y="741" fill="#536783" font-size="17" font-weight="500" text-anchor="start">Illustrative planning map</text>
+</svg>

package/docs/jira.md

@@ -0,0 +1,66 @@
+# Bring Jira into the plan
+
+Use Jira for the official issue facts and Sightline for the planning conversation around them. The optional
+helper supports **Jira Data Center**, uses Python's standard library and makes read-only HTTPS requests.
+The HTML never contacts Jira. [Back to the tour](../README.md#how-it-works).
+
+## Try the example before connecting a server
+
+Open [the Northstar plan](../examples/northstar/plan.json), then connect its sibling **jira** folder in
+**Settings → Jira connection**. It contains synthetic files and needs no token. Choose **Work → Sort Jira work**
+to see how incoming issues can be placed without editing Jira facts.
+
+## Configure your own trusted helper
+
+`npx @troylar/sightline helpers` prints the folder that holds the helpers, stamped with the app's version. Use
+that absolute path in place of `/trusted/helpers` below. From a source checkout, run `./build.sh` and use **dist/**
+(`node bin/sightline.js helpers` prints it). Python 3.10+ is required for the helpers; the HTML app itself does not
+require Python. The helper only reads from Jira: it never creates, edits or deletes anything there.
+
+```sh
+python3 /trusted/helpers/sightline-jira-sync.py setup
+python3 /trusted/helpers/sightline-jira-sync.py fields
+```
+
+`setup` asks for your Jira HTTPS address and personal access token and stores the token in your OS credential
+store. Do not put tokens in a shared folder, plan, command argument or screenshot. `fields` helps identify your
+server's Epic Link, Sprint, Story Points and Parent Link fields. Use each command's `--help` for local field overrides.
+If your Jira puts a feature (or another level) between epics and stories through Parent Link, the sync needs that
+field to trace each story to its epic. Without it, the sync says so after each run, and **Sort Jira work** explains
+why such stories show with **No epic**. Sort Jira work groups a story under the first epic above it, through any
+feature in between, even when that epic isn't on the plan.
+
+Save a JSON plan first. Then, with an explicit Jira board ID and JQL that you choose locally:
+
+```sh
+python3 /trusted/helpers/sightline-jira-sync.py sync /path/to/plan.json --board 42 --jql 'project = DEMO' --save
+```
+
+`42` and `DEMO` are invented examples. Replace them deliberately with your own board and search. The helper reads
+more than search results, including relevant issue, board and sprint endpoints. Server/search configuration stays
+local to the token holder and is never taken from the shared plan. `--save` remembers this plan's sync settings on
+that computer. The default output is a **jira** folder beside the plan.
+
+## Connect the output in Sightline
+
+1. Open the matching plan in Sightline.
+2. Choose **Settings → Jira connection**, then connect the local **jira** output folder.
+3. Check the sync timestamp, coverage and any setup warnings. If the plan's sprints differ, inspect **See the change
+   first** before choosing to follow Jira's sprints.
+4. Use **Work → Sort Jira work** to arrange returned issues. Open an item: **From Jira** stays read-only;
+   **Added here** is your planning context.
+   Your assistant can propose where each issue goes (the **Sort Jira work** skill); you review every placement in
+   **Changes** before anything joins the plan, and nothing is written to Jira. See
+   [Sorting Jira work](assistant-workflow.md#sorting-jira-work).
+5. An initiative or task linked to an issue shows the issue's description as its story, marked **From Jira**
+   (Sightline 1.109.0 or later, with the matching sync). The sync reads descriptions only for issues the plan links.
+
+For repeated syncs, run `python3 /trusted/helpers/sightline-jira-sync.py watch`. Read `install --help` before
+configuring startup behavior. Run trusted helper code from your own computer, never a mutable shared folder.
+
+## Read freshness literally
+
+A local timestamp describes the most recent successful sync in the files Sightline read. It doesn't prove Jira
+is current now, that your search covers everything, or that a cloud provider delivered the latest files. Missing
+issues are “not in the last sync”; their surrounding plan work is retained. Jira status and sprint dates remain
+Jira-owned. Sightline proposals do not write changes back to Jira.

package/docs/large-roadmaps.md

@@ -0,0 +1,93 @@
+# Get your arms around a large roadmap
+
+If you are new to Sightline, read the [worked planning session](roadmap-planning-example.md) first. It shows how
+a set of overlapping requests becomes a source reconciliation, a capacity question, and three decisions.
+
+Start with the mess you actually have: goals, commitments, meeting notes, questions, Jira work, and more ideas
+than the team can tackle at once. Use your external AI tool to turn that into a sequence of decisions, with
+reviewable changes attached. [Connect your assistant first](assistant-workflow.md).
+
+You do not need a perfect backlog before starting. You do need to know which evidence the assistant can see.
+
+## Check the planning evidence first
+
+Ask:
+
+> Read the current context. Tell me which plan and snapshot it represents, what it includes, what is omitted,
+> and which parts of this planning question the evidence cannot answer.
+
+Public-source 1.94.0 supports roadmap editing context. **Richer automatic capacity, dependency, risk and decision
+exports require 1.96.0 or later**. Check for `planning.version: 1` and read `coverage`; do not assume a newer
+export because the guide describes one. [Build availability](availability.md).
+
+On an older build, provide any additional evidence deliberately, as separate read-only input to your tool.
+Do not tell it to search personal folders or overwrite your shared plan. Without the relevant evidence,
+organization is possible but a capacity-backed delivery forecast is not established.
+
+## 1. Empty your head without committing the team
+
+Give the tool a notes file or paste a substantial section into its conversation. Keep a copy of the source.
+
+> Separate these notes into agreed changes, ideas, constraints, and open questions. Match them to existing
+> work by stable ID where possible. Flag possible duplicates; do not merge them just because their names are
+> similar. Keep every source item accounted for. Ask only the questions needed to avoid a consequential guess.
+
+For a long source, work in sections. At the end ask for a reconciliation: incorporated, matched to existing work,
+left as an idea, or awaiting a decision. A summary alone does not establish that nothing was dropped.
+
+## 2. Reorganize around outcomes
+
+> Suggest a clearer arrangement of this work. Explain the user or business result for each outcome, what
+> belongs together, and what should stay separate. Reuse existing IDs. Show the proposed moves before writing them.
+
+Workstream membership is context, not evidence that everyone in a group has interchangeable skills. Keep work
+outside the selected quarters visible in the discussion. A move is not a reason to recreate the item and lose its links.
+
+Start with one representative area, review it, then continue. Changes that depend on one another belong in one
+atomic proposal; unrelated changes should be independently reviewable. The current protocol limits a change to
+25 operations, a batch to 100 changes, and one Apply action to 25 changes. Do not hide a partial reorganization
+behind a claim that the whole roadmap was updated.
+
+## 3. Ask what actually constrains delivery
+
+For a 1.96.0+ planning export, ask:
+
+> Use the supplied capacity calculations and issue facts. Show which people or periods are constrained,
+> where load or capacity is unknown, and which dependencies or decisions could stop the work. Separate
+> calculated facts from assumptions. Give me the next three decisions, with the evidence behind them.
+
+The export's capacity rows compare known scheduled Jira points with configured availability. They do not
+include all remaining effort, plan-only work, support reserves, meetings, or unestimated demand. Do not convert
+initiative weeks or task duration into per-person effort without an explicit assumption. Unknown is not zero.
+Do not add overlapping sprint capacities as if they were separate time, or compare different teams' points
+without a shared estimation basis.
+
+A useful answer might say:
+
+> This person has work scheduled against zero configured allocation. These issues are unestimated. The
+> available sprints do not cover the roadmap's target year. We need those gaps resolved before calling the plan feasible.
+
+That is an illustrative answer, not a customer result or a measured promise about your team. The
+[context reference](assistant-workflow.md#planning-data-for-your-external-assistant) explains the calculations.
+
+## 4. Compare choices before changing the plan
+
+> Compare protecting the launch date, protecting the team's workload, and reducing scope. For each choice,
+> list what would move or be deferred, the assumptions, and the evidence still missing. Do not apply anything.
+
+Keep hypothetical scenarios in the conversation or a separate working document. Sightline does not currently
+provide an automatic scenario simulator or a saved scenario workspace. Recalculate when inputs change; a
+persuasive explanation is not validation of the numbers.
+
+Choose one option, then ask for the supported changes as a proposal batch. Starts-after links, people, workstreams,
+milestones, gates, risks and decisions are actions the batch can carry; capacity rates and sprint settings still need
+manual UI updates.
+
+## 5. Close the loop
+
+Review the before/after values, apply the selected changes, follow the visible save state, and let the assistant
+read fresh context and matching results. Ask what remains unresolved. Receipts describe this browser's review;
+they are not a shared audit log or proof of cloud delivery.
+
+For a recurring meeting rhythm, use [team planning](team-planning.md). For a quick first win, use the
+[prepared Northstar session](getting-started.md).

package/docs/onedrive.md

@@ -0,0 +1,62 @@
+# Using OneDrive
+
+Sightline opens the plan file on your computer. OneDrive carries that file between computers. A successful Sightline save confirms a local save; it does not confirm that teammates have received it.
+
+## Set up the shared plan
+
+1. Put the shared JSON or YAML plan in a team folder that everyone using it is allowed to read and edit.
+2. On each computer, make the plan and any connected Jira files available offline. In File Explorer or Finder, choose **Always keep on this device**. Microsoft documents this option for offline availability in [Sync SharePoint files and folders](https://support.microsoft.com/en-us/onedrive/sync/sharepoint-training/sync-sharepoint-files-and-folders).
+3. Wait for OneDrive to finish downloading the folder, then open Sightline in Edge or Chrome. Choose **File → Open shared plan** and select the local file. Connect the local Jira folder if your team uses it.
+4. Leave **File → Check for teammates' saves every 15 s** on to pick up local changes; this is enabled by default unless you previously turned it off. Use **Refresh** before starting work. Check OneDrive's own status before handing the plan to a teammate.
+5. Edit one at a time: **Start editing**, **Save**, then **Done editing**. Agree who is editing when a computer is offline or sync is paused.
+
+OneDrive and your organization control folder access. Sightline's views, author stamps and edit lock are not access controls.
+
+## Know which version you are seeing
+
+The page shows its last confirmed local read or save. Automatic checks can notice a teammate's save only after OneDrive delivers it to your computer. Refreshing Sightline does not force a cloud download. Use OneDrive's status to check upload/download progress.
+
+The edit lock is stored in the same shared file, so it also travels through OneDrive. Two offline computers can each believe editing is available. Sightline checks local content before saving, keeps backups for detected clashes, and preserves unsaved drafts, but it cannot guarantee that an unseen cloud update will never cross a save. Keep both versions if OneDrive produces a conflict copy.
+
+If another person starts editing while you have unsaved changes, Sightline keeps your browser copy, undo history and recovery draft. Review the conflict choices before replacing either version. After a file-read failure, **Try again** reconnects from your current browser contents, including edits made since the failure. An unchanged file preserves your edits; a changed file is merged or presented for conflict review. A newer unsupported file format keeps your edits available for download and requires updating Sightline before saving.
+
+## Keep assistant folders personal
+
+Keep the shared plan where the team can access it. Connect each person's assistant to a separate private folder for each device and plan, with one active Sightline tab writing to that folder. A local folder is simplest. If you sync the assistant folder, use distinct device folders rather than having two devices write the same outputs.
+
+Sightline writes context and results; your assistant writes proposed changes. Names, people and work descriptions in these files are team information. Give the folder only the access it needs. Browser permission to open a folder does not make it private.
+
+Context and results are separate files. Before combining them, compare the plan revision and Jira sync timestamp. Results reflect the reviewing browser's Apply, Skip and edited operations, not a shared audit log. Unchanged navigation and polls do not repeatedly rewrite outputs. See [Work with your assistant](assistant-workflow.md) for the connection steps.
+
+## Review a conflict copy
+
+Keep the live plan and conflict copy under their existing names. Choose **File → Review another copy…** and select the copy. The **Review another plan copy** dialog compares it with the current shared file without changing either file. Read the warning about work found in the current plan but missing from the copy. A later timestamp does not establish that the copy is the right version.
+
+Choose **Download both copies** to keep separate backups, or **Decide later** to leave the live plan alone. If you deliberately want the entire copy as your starting point, choose **Use this copy to edit**. Confirm the warning: a later Save can replace current contents and remove newer work. Sightline downloads both originals, marks the shared plan as being edited, and prepares the copy as unsaved edits. It does not automatically save the copy's contents or select individual fields to recover.
+
+Inspect the draft, restore any newer work you intend to keep, then use normal **Save** and **Done editing**. Previewing never deletes work. Copy contents reach the shared plan only after your explicit choice and Save. Finish or put aside existing unsaved edits before starting a review; a different plan, a newer unsupported format, different plan dates or sprint settings, another person's active edit lock, or a shared file that changed during review must be addressed first. Keep those copies for a separate comparison.
+
+## When an update doesn't stay saved
+
+After a quick update, Sightline reads the file again. If a save at the same moment overwrote the update, it is put back, once. If the file changes back again, something keeps restoring an older version: another open copy of the plan (another tab, browser or computer) or a sync tool such as OneDrive. Sightline stops, downloads your version as a backup and says so in a red notice, naming whoever saved the file last when the file says. Close the other copies, let OneDrive finish syncing, open the plan in one tab and make the change again.
+
+## Two-device check before a team rollout
+
+**Not executed:** no real OneDrive two-device environment was available for this change. The matrix below is a manual check to perform on your organization's actual computers and sync configuration. Browser file-operation tests use simulated file handles; they do not prove cloud synchronization or conflict-copy behavior.
+
+Create an isolated test folder on OneDrive. Copy `test/fixtures/sample-plan.json` into it as `sync-check.json`; it contains invented people and work. Use the same Sightline build on both computers. Download and pin the test file on both, confirm OneDrive is up to date, and preserve an initial backup outside the shared folder. Use private, distinct assistant folders. Do not connect real Jira or use a real team plan for this check.
+
+Record the operating systems, browser and OneDrive versions, Sightline version, device labels A/B, and each computer's local plan revision. For each case, note what OneDrive reports, what Sightline reports, the file values on both devices, and whether a backup or conflict copy exists. A changed timestamp alone is not proof that both edits survived.
+
+| Case | Try | Check and expected limitation | Result |
+|---|---|---|---|
+| Normal handoff | A changes an invented task, saves and finishes editing. After OneDrive finishes, B refreshes. | B sees A's value and revision. Record sync delay; Sightline cannot make the cloud delivery immediate. | Not run |
+| Offline then reconnect | Take A offline. Edit and save an invented field. Confirm B still sees its earlier local copy. Reconnect A, wait for OneDrive, then refresh B. | A can save locally. B must not be assumed current while A is offline. Both eventually show the intended value, or a clash/copy remains available for review. | Not run |
+| Simultaneous different fields | With both devices at the same initial revision, pause sync or take both offline. A and B change different fields, save, then reconnect both. | Inspect the actual resulting files. Local checks cannot serialize unseen remote writes. Do not count this as passing if one edit disappears without a recoverable version. | Not run |
+| Simultaneous same field | Repeat with different values for the same invented field. Preserve both values before reconnecting. | A disagreement must remain reviewable through the final file, backups or a conflict copy. Do not expect Sightline to infer which value is correct. | Not run |
+| File replacement | With B displaying a clean test plan, replace A's local test file with a valid copy under the same filename; let it sync. Refresh B. | B must show the replacement or a clear read/reconnect problem. Replacing a file may affect remembered browser handles; reconnect if needed. Never repeat this on a real plan. | Not run |
+| Browser reconnect | Close and reopen Sightline on B, then reconnect the plan and private assistant folder if prompted. | Permission prompts are browser-local. Confirm the correct plan/device folder and that another device's outputs are not overwritten. | Not run |
+| Unsaved work during interruption | On a synthetic plan, keep an unsaved field edit on B. Have A acquire the lock, then let B try Start editing. Separately interrupt B's file access, type another edit, and use Try again after restoring access. | B's latest contents and undo history remain available. A changed file is merged or requires conflict review; refusing a lock never discards B's draft. Confirm actual browser/file-provider behavior. | Not run |
+| Conflict-copy review | If a conflict copy is produced, preserve it and the live file. Compare their invented changes without replacing either. If none is produced, create an explicitly labeled synthetic divergent copy for the review exercise. | A synthetic copy tests review, not OneDrive's conflict handling. Preview changes neither file, missing current-only work is reported, and both originals can be downloaded. Replacing contents requires explicit copy choice and normal Save. | Not run |
+
+After each case, restore the synthetic baseline only when all test copies and outcomes have been recorded. Pause test editing until both devices are at the same baseline. Keep results separate from real team work.

package/docs/performance-workspaces.md

@@ -0,0 +1,39 @@
+# Workspace performance checks
+
+The standalone benchmark compares an archived build with the current build using jsdom and synthetic data derived
+from `test/fixtures/sample-plan.json`. It installs no additional dependencies and is informational, outside `test/run.sh`.
+
+Build the current page, then run:
+
+```bash
+./build.sh
+node test/performance-workspaces.js /path/to/original/sightline.html dist/sightline.html 5 > /tmp/workspace-performance.json
+```
+
+The final argument is the number of samples per workspace (default 5, minimum 3). The script warms each workspace
+twice, measures synchronous navigation/render work, and reports median/minimum/maximum milliseconds, DOM node counts,
+and mean time in selected rendering functions. Function timings include nested work; do not add them together.
+
+The scenario has 120 epic initiatives, 600 Jira stories, 120 plan tasks and 60 deliverables, using the fixture's people
+and workstreams. Dates are fixed around September 30, 2026. It visits Timeline, Today, Sprint, People, Roadmap and
+Status update in order, retaining hidden workspace DOM as normal navigation does. The assistant is disconnected.
+
+During the workspace navigation change, profiling identified document-wide navigation selectors as unnecessary work.
+Caching the fixed navigation buttons and elements reduced `renderMainNav` from roughly 25–95 ms to about 0.1 ms
+per render across this scenario. Navigation regression checks cover the cached elements' behavior.
+
+These are jsdom JavaScript/DOM measurements, not browser layout, paint or interaction latency. The recorded comparison
+ran alongside other checks, so whole-page timings are noisy and are not release thresholds or a promised speedup.
+For repeatable comparisons, stop other heavy work and repeat with build order reversed. Use real-browser profiling
+before making claims about perceived responsiveness.
+
+Hidden Timeline and setup-table rendering is deferred until the relevant workspace is visible. Timeline visibility
+is restored before measuring its geometry; returning to it draws current data. Shared model refresh, Jira facts,
+freshness and assistant context remain independent of chart visibility. `harness106` checks hidden-render call counts,
+return-to-Timeline behavior, filters, selection/deep links, Days/Weeks and live Jira facts.
+
+Text inputs update the model, history and dirty state synchronously, then combine derived rendering while typing.
+The deferred update is cancelled when a full render supersedes it. Regression checks cover immediate model changes,
+undo, cursor retention and the deferred screen update without depending on a machine-specific time threshold.
+
+The connected-assistant regression harness (`harness100`) counts payload builds and file writes. View changes and unchanged foreground checks must add neither; real saved-source, Jira, proposal and receipt changes must still refresh outputs. A Chrome Incognito smoke test also verified that ordinary navigation left context/results modification times unchanged after a proposal was reviewed and applied.

package/docs/roadmap-planning-example.md

@@ -0,0 +1,92 @@
+# A planning session when everything seems to be a priority
+
+Imagine you coordinate Integrations, Search, and Platform. A launch is approaching, new requests keep arriving,
+and the same specialist is needed in several places. The Jira backlog tells you about individual issues. Your
+planning problem also includes commitments, rough ideas, dependencies, and decisions spread across conversations.
+
+This is an **illustrative planning exercise**, not a captured model response, customer result, or the plan shown
+in the Northstar screenshots. Its sample numbers and names are invented. Use it to understand the workflow;
+[open the smaller prepared example](getting-started.md) to try the actual review controls.
+
+## Start with what people actually said
+
+Keep the original notes and give each source a reference. They do not need to be a clean backlog.
+
+| Source | Rough input |
+| --- | --- |
+| N01 | We agreed that customer-context lookup belongs in the launch. |
+| N02 | Sales also wants a customer history panel. Is that the same thing? |
+| N03 | Search relevance has to improve, but nobody agreed what “better” means. |
+| N04 | Search needs Platform's index migration before its new retrieval work can finish. |
+| N05 | The migration has no confirmed completion date. |
+| N06 | Offline search came up as an idea. Nobody committed to building it. |
+| N07 | Search and Integrations both asked for the same Platform specialist in the launch period. |
+| N08 | Platform's next sprint has 6 points of configured capacity and 8 points already scheduled, on its own estimation scale. |
+| N09 | Five requested Platform issues have no estimates. Support demand is not represented in those capacity numbers. |
+| N10 | Leadership wants a launch update explaining what is committed, what is uncertain, and what needs a decision. |
+
+Connect your plan's [private assistant folder](assistant-workflow.md), then give your external tool these notes
+and the relevant planning evidence. Ask it to read the current context before interpreting them. On public
+1.94.0, the automatic context is narrower than the 1.96.0 planning export; additional evidence must be supplied
+deliberately. [Check availability](availability.md).
+
+> Reconcile every source against the current plan. Reuse existing IDs where there is a match. Separate agreed
+> scope, possible duplicates, ideas, constraints, and decisions. Do not invent owners, estimates, or dates.
+> First give me a decision brief, not a rewritten plan.
+
+## Turn the input into a few decisions without losing the details
+
+A useful reconciliation could look like this. These are suggested interpretations of the invented notes,
+not automatic actions:
+
+| Source | Interpretation | What happens next |
+| --- | --- | --- |
+| N01 | Agreed launch scope | Match the customer-context outcome in the plan; retain its ID. |
+| N02 | Possible overlap with N01 | Ask whether the history panel is part of lookup or additional scope; keep both sources until resolved. |
+| N03 | Outcome needs definition | Decide what improvement will count before treating it as a clear commitment. |
+| N04 | Dependency | Verify the migration link in the plan and which work it blocks. |
+| N05 | Missing delivery input | Ask for the migration forecast and its assumptions; do not make up a date. |
+| N06 | Uncommitted idea | Retain offline search without assigning an owner or target. |
+| N07 | Shared resource constraint | Ask the team to resolve the competing demand and confirm actual allocation. |
+| N08 | Known scheduled load exceeds configured capacity | Review the 8 scheduled points against 6 configured points for that sprint. |
+| N09 | Additional demand is unknown | Obtain estimates and account for support before calling the load complete. |
+| N10 | Communication request | Draft an update after separating confirmed scope, uncertainty, and decisions. |
+
+Every source remains accounted for. Matching a request to an outcome does not mean its scope was accepted;
+a similar title does not prove a duplicate.
+
+## Make the capacity discussion specific
+
+Within Platform's one sprint and estimation scale, the supplied numbers show **2 more scheduled points than
+configured capacity**. They do not tell you the full shortfall: five issues are unestimated and support is absent.
+They also do not establish that the launch is feasible or predict a finish date.
+
+Before relying on that comparison, confirm that the input is current, the sprint periods match, the specialist's
+allocation is correct, and the scheduled issues are in scope. Do not combine overlapping sprint capacities or
+add points from different teams as if they were interchangeable.
+
+The next decisions are concrete:
+
+1. **Resolve launch scope.** Is N02 part of N01? What would count as success for N03? Until answered, the launch demand is unclear.
+2. **Resolve the shared bottleneck.** Which work gets the specialist's time, and what does that mean for N04's migration dependency?
+3. **Choose a tradeoff using complete enough evidence.** Clarify N09, then discuss reducing scope, sequencing work later, or changing the target. Record what remains uncertain.
+
+Ask the assistant to explain alternatives in the conversation. Sightline does not provide an automatic scenario
+simulator. A confident answer without the missing inputs is still an assumption.
+
+## Turn the chosen direction into reviewed changes
+
+Once the team decides, ask for the supported edits as proposals. For example, retain N06 as an unscheduled idea
+and refine an existing outcome's wording after its scope is agreed. Review the actual before/after values in
+Sightline. Edit, skip, or apply each proposal, then follow the visible save state.
+
+Dependency, allocation, risk, or decision changes may need normal UI edits. The assistant's operation guide defines
+what it can propose; a read-only export does not grant it additional editing powers. Writing proposals never
+authorizes it to overwrite the shared plan or Jira files.
+
+Finally, have the assistant reread fresh context and matching results and draft the update requested in N10:
+confirmed scope, changes actually applied, unresolved questions, and the next decision. Check it before sharing.
+The next meeting starts from that record rather than rebuilding the conversation.
+
+[Work through your own large roadmap](large-roadmaps.md) · [Connect your assistant](assistant-workflow.md) ·
+[Try proposal review with Northstar](getting-started.md#review-two-changes) · [Back to Sightline](../README.md)