create-pmos 0.516.0 → 0.518.0

package/workspace/guide/console-calendar.md

@@ -1,178 +1,17 @@
 ---
 type: Guide
-title: "Guide: the Calendar tab of the console page"
-description: "The Calendar tab of the console page (/): Calendar and Notes, the five zooms, the highlights, the layer chips, the markers, the context of a meeting, free time, the tidy-up suggestions and the empty states."
-timestamp: 2026-10-15
+title: "Meeting focus over Google Meet: the Chrome extension"
+description: "What the PMOS Chrome extension shows over a Google Meet call, what it reads, and how to add it with pmos extension."
+timestamp: 2026-11-03
 ---
 
-# Guide: the Calendar tab of the console page
+# Meeting focus over Google Meet: the Chrome extension
 
-The Calendar tab of the console page (`/`) shows time. It shows what happens and what falls due, by date. At the top it shows a short deck of headline cards about your calendar, for example a conflict or a meeting with no time to prepare. The deck shows nothing when PMOS has no card about your calendar. The tab shows no task list and no strategy panel. Your due items live in Work. The strategy and progress panels live in Reports and Initiatives.
+The calendar is in Home: press the calendar icon in Your day's header. A meeting opens in the Viewer, where you record it and follow its notes. [Notes](notes.md) explains recording. This page explains the Chrome extension, which shows a small PMOS panel over a Google Meet call.
 
-## Calendar and Notes
+## Add the extension
 
-The switch at the start of the bar has two parts. **Calendar** shows the grid. **Notes** shows your notes.
-
-In **Notes**, the list is at the left, under the heading **Notes**. The notes are in groups by what they are about: **Portfolio** first, then one group for each board, in the order of the portfolio. **Not linked** is the last group. A note linked to an initiative from an earlier version, with no board, is in **Initiatives**. In each group, the newest meeting is first. A note with no meeting is placed by when its recording started, or else by when it was made. The number shows how many notes the list shows. Type in **Search notes** to keep only the notes that have every word. The search reads the title, the board, the initiative, the summary, the decisions, the next steps and what was said. A private note is found by its title only. A row shows when the note was made and its length. In a board group, a row shows its initiative, or **board** when the note is about the whole board. A row also shows **recording** or **paused** while the note is held, **no meeting** when the note has no meeting, and a warning mark when a statement differs from a file.
-
-Notes of one regular meeting are a **series**: the same calendar series, or the same title. A series is one row. The row shows how many meetings it has, and how many next steps are still open. Press the arrow on the row to show its last three meetings. Press the row to open the series at the right. Notes older than 30 days fold into **Older than 30 days** at the end of each group. Press it to show them. A recorder left on after the meeting shows its length up to the last line heard, not up to when it stopped.
-
-The series page shows what carries from one meeting to the next:
-
-- **Next one** shows the next meeting of the series and what to bring up: the next steps still open after several meetings, the questions asked in several meetings, and your own lines. Type in **Add something to bring up** and press `Enter` to add a line. Press the cross to remove it.
-- **Still open** shows each next step not yet done, its owner, the number of meetings it was raised in, and when it was last heard. Press **Done** when it is done. It stops carrying over. **Open again** puts it back.
-- **Decided so far** shows each decision of the series, newest first, with why.
-- **Keeps coming up** shows the topics heard in several meetings.
-- **Still unanswered** shows the open questions. Press **Answered** when a question has its answer.
-- **Every meeting** shows each note of the series with its gist. Press one to open it.
-
-A private note adds its title and date to the series, and nothing else.
-
-A note in a series shows the series and its place, for example `IDPF - DSU · 21 of 21`. Press it to open the series. The arrows open the meeting before and the meeting after. **After** shows **Since the last one** first: each next step of the meeting before, as **Done**, **Raised again** or **Not mentioned**, then the new next steps. Press **Not part of this series** to take a note out of its series. Press **Add to a series** to put it in one.
-
-Press a row to open the note at the right. The note has three stages. Press **Before**, **During** or **After** to change the stage.
-
-Under the title, the note shows its meeting. Under the meeting, it shows what the note is about: the **Portfolio**, a board (for example a stand-up or a sprint planning), or an initiative on its board (for example `IDPF › Partner API rate limits`). Press **Link to a meeting** to link the note to a meeting. Press **Choose what it is about** to open one menu: **Portfolio** (every board), each board (the whole board), and the current and next initiatives of each board under it. When the note has a link, press **Change** to choose another one, or **Not linked** in the menu to remove it. The note moves into its group.
-
-- **Before** shows what the note kept about its meeting: the agenda, what the meeting is for, what to do to be ready, what to read first, the people, and the meeting: its time, its place and who organized it. A tick shows an agenda item that was heard in the transcript. A note with no meeting says so, and has **Link to a meeting** and **Choose what it is about**.
-- **During** shows the live notes while the note is recorded or paused. At other times it shows the transcript.
-- **After** shows **Replay** first when the sound of the note is kept on this machine. Then it shows the overview, the decisions with why, the next steps with owner and due date, the open questions, the statements that differ from a file, the highlights and the screenshots of the shared screen (**Screen**; press one to see it large). The transcript is folded at the bottom. Click a text to correct it: the summary, a decision and its why, or a next step, its owner and its due day. Press `Enter` or leave the text to save it. Press `Esc` to cancel. Empty an owner or a due day to clear it. A decision caught while the meeting was recorded has no why. Before the final notes are written, press **Write a summary of the meeting** to write your own summary; empty it to go back to the caught one. **Make task** adds a next step to the note's initiative.
-
-A note that is recorded now opens on **During**. Other notes open on **After**. **Show in the calendar** goes back to the grid, on the day of the meeting, with the meeting selected. The copy button puts the note on the clipboard as Markdown.
-
-In **Notes**, the zoom, the arrows and the calendar keys do nothing.
-
-## Zoom and move
-
-Use **Day**, **Week**, **Month**, **Quarter** or **Year** to change the zoom. Use the arrows to go to the previous or the next period. Press **Today** to come back to today.
-
-The keys work too. Press `+` to zoom in and `-` to zoom out. Press the left or the right arrow to move. Press `t` for today. On a touch screen, swipe sideways to move and pinch to zoom.
-
-## Layers
-
-The chips under the zoom bar are the layers. On a screen wider than 600 pixels they are folded: press **Layers** in the zoom bar to show them, and press it again to fold them. They stay shown until you fold them or reload the page. Each chip shows the number of items in the range. Press a chip to hide its items, and press it again to show them.
-
-| Chip | What it shows |
-|---|---|
-| Meetings | The meetings of your calendar. |
-| Milestones and due dates | The promised dates of the initiatives, and the milestones and due dates of their plan items. |
-| Releases | The release dates. |
-| Report dates | The dates on which a report goes out. |
-| My due items | The due dates of your own items, as markers. |
-| Free time | The free blocks of your working day. The chip shows the number of blocks in the range. |
-| Tidy-up | The suggestions to tidy up the calendar of the range. This chip is off at the start. |
-
-All layers and Free time are on at the start. Tidy-up is off.
-
-On Month, Quarter and Year there is one more chip, **Routine**. It shows the number of routine items in the range: report drafts, reports that go out daily or weekly, recurring meetings, stand-ups, 1:1s and due items on track. These items are counted, not listed. Press **Routine** to show every item as a marker, and press it again to go back to the highlights.
-
-## Highlights
-
-Every zoom starts with a short summary above the grid, for example "October highlights". It names what matters in the range:
-
-- the releases, and the milestones that are on track
-- the key meetings, on Day, Week and Month only. A meeting is key when it is not routine. Month names the two biggest.
-- the reports that go out
-- **Watch:** the milestones and releases that are late or at risk, and the due items that are late
-
-Press a name to open the item in the detail column. When nothing significant falls in the range, the summary says so.
-
-## The grid
-
-- **Day** shows the timeline of the day. The markers of the day are in a strip above it, side by side on one line.
-- **Week** shows a timeline for each day. Each day name has the hours of meetings of that day and a small bar. The bar has three parts: time tied to a promise or a decision, routine time, and the rest of a 6 hour day. The markers of each day are in a strip under the day name. Press a day name to open that day.
-- **Month** shows a cell for each day. A cell shows the highlight of the day in one sentence, for example "SSO general release ships." Under it, a quiet line counts the rest, for example "1 due · 2 routine". Press that line or the day number to open the day. A line under the grid says what is counted and not named. With **Routine** on, a cell shows the number of meetings and up to three markers instead, and "+2" opens the day with the other markers.
-- **Quarter** shows a column for each month. **Year** shows a column for each quarter, with a button for each of its three months. Each column shows its highlight and a quiet line, for example "24 meetings · 3 due · 9 routine". Quarter and Year are stricter than Month: they name only milestones, releases, reports that go out and late items. Press a column's title to open that month or quarter. With **Routine** on, a column shows its markers instead.
-
-On Day and Week, the reports of a day are in one **Reports** chip with their number, for example "Reports 2". On Day it also says what they are, for example "2 scheduled · 1 not issued". Press the chip to show the reports under it, each with its state: **scheduled**, **not issued** or **issued**. Press it again to fold them. A report that was not issued after its day is late for a week: it stays out of the chip with an amber edge. The reports of a horizon scan are documents, not report dates, so they are not on the calendar. Two report schedules with the same name show once on a day.
-
-Titles wrap onto more lines. They are never cut.
-
-A marker has a symbol and a short title. A red edge means late or at risk of missing. An amber edge means at risk.
-
-A meeting is blue when it is tied to a promise or a decision, and grey when it is routine. A red meeting is blocked: its prep waits on someone. A coming meeting with prep left ends its time line with "prep to do". A past meeting that PMOS holds a record for ends it with "held". A line under the grid explains the colours.
-
-## Select a marker
-
-Press a marker to show its detail in the side column. The detail shows the title, then a row with where the item lives, the kind, the date and its initiative. The link under it opens the item where it lives: an initiative opens in Initiatives, your item opens in Work, and a report opens in Reports. A marker has no action of its own. You act on the item in its home.
-
-## Select a meeting
-
-Press a meeting to open it in a popup at the right of the screen, as a session opens. The popup has four sizes: **Normal**, **Half**, **2/3** and **Whole**. It opens at the size you used last. Press `Esc`, **Close** or the page behind it to close it. When the meeting has a note, at **Half** and wider the note is beside the meeting: its title, the first lines of its summary and **Open the note**. **Focus**, **Open the note** and a link to another page close the popup first.
-
-In the popup, a row shows where the meeting lives, the people and the initiative. Each line has a link to its source. When all the lines come from one note, the note is named once under them. The calendar popup over other pages shows the meeting in its side column instead.
-
-- For a past meeting, **What came out of it** lists the decisions and actions of its note. **What moved after it** lists the items that changed within 48 hours and refer to the meeting or its initiative.
-- For a coming meeting, the detail shows these parts. A part with no record is left out.
-  - **In short**: the purpose from today's brief, or the initiative and its status. It also counts the items that are blocked, late or due today.
-  - **What matters today**: the items of the initiative that are blocked, late or due in the next 2 days, and your own items on it. Each line opens the item.
-  - **Since the last one**: the last note of the same meeting (the same title or calendar series). It shows the summary, the decisions and the next steps, and how many earlier notes there are. **Open the last note** opens it in **Notes**. For a private note, only its title shows.
-  - **To prepare**: what is prepared, what is still open, and how to be ready, from today's brief. The links from the brief follow.
-  - A last line names the sources that PMOS used.
-
-### What a meeting is about
-
-A coming meeting is about the **Portfolio**, one **board** or one **initiative**. A switch under the title shows the level, and a line next to it tells you why PMOS chose it. PMOS uses the first of these that applies:
-
-1. The level you set with the switch.
-2. The initiative in today's brief.
-3. The level of the last note of the meeting.
-4. A board that the title names: its name, its id or one of its Jira project keys, as a whole word. For example, "IDPF - DSU" names the IDPF board.
-5. The word "portfolio" in the title.
-
-To set the level, press **Portfolio**, **Board** or **Initiative**. If there is more than one board or initiative, pick one from the list. The level applies to every occurrence of the meeting (the same calendar series, or the same title). To remove a level that you set, press **Unlink**. PMOS keeps the level next to the calendar. It does not change your calendar.
-
-The level changes what the detail reads:
-
-- **Initiative**: the parts above.
-- **Board**:
-  - The active sprint from Jira: its name, the working days left, its end date and a bar of done, in progress and to do.
-  - **What matters today**: the blocked tickets of the sprint, the initiatives on the board that are late or at risk, and the new asks in triage. A ticket opens the board's Sprints and an ask opens Triage.
-  - For a planning meeting, the list is called **To settle in planning**, and the sprint line also shows the next sprint and how many open tickets can carry over.
-- **Portfolio**:
-  - **Boards** lists each board with its health and its counts.
-  - **What matters today** shows the late and at-risk initiatives on all boards, a release in the next 14 days and the new asks.
-
-At every level, **Since the last one**, **To prepare** and the sources line stay.
-
-When the meeting has a note, the detail has **Open the note**. It opens the note in **Notes**.
-
-When PMOS holds nothing for a past meeting, the detail says so. For a coming meeting, **What PMOS knows** tells you what is missing (no level, no earlier note) and what to do: set the level with the switch, or take a note in the meeting. It does not guess.
-
-### Meeting focus
-
-**Focus** opens one calm page for a meeting that is today. It shows on the detail of a meeting that has not ended, and next to the recording on the header while a meeting is recorded. An untitled note that records has **Focus** too: the page opens on the note, with the conversation and the captured items, and no topics or material. The page covers the console. **Leave focus** gives the console back. Leaving does not stop the recording. The page stays open when you reload it. From the recording, the page finds the meeting by its start time and title, so it also finds a meeting that has no calendar id, or that moved on the same day after you started to record.
-
-The page has these parts:
-
-- **Header**: the title, the time, the initiative and the number of people. Before the start, the clock shows the time until the start. After the start, it shows the time that passed and the time left. **REC** shows while the meeting is recorded. **Start recording** and **End meeting** work as they do in the note dock. Under the clock, a thin bar shows the topics in the order the room talked about them. The topic that is open now is the brightest.
-- **Now line**: the topic the room is on and how long. It also gives the number of topics and how many the room has not covered. **Captured** and **Note** open the items captured so far and the live note.
-- **What's being said**: one sentence on the talk, and up to four context chips. A chip opens its detail, its link, or the item it names.
-- **Material**: each link in the meeting shows as a card. **Open** and **Present** open the deck in a new tab. For a Google Slides or Google Docs link, press **Show the preview here** to see the preview that Google draws. PMOS loads nothing from Google until you press it. Share that tab in the call. Other links, for example Confluence, show as a card with **Open**. Before the start, the page lists what is ready to open, what to bring and what is open from the last meeting. PMOS shows nothing to the room.
-- **Conversation**: the last two lines of the room, then the notes from PMOS. Only the newest note is open. Press a shut note to read it. Each note gives what it heard, why it came now and where it comes from. PMOS keeps some notes until the right moment. Open **PMOS is holding** and press a note to show it now.
-- **Ask PMOS quietly**: type a question under the conversation. Only you see the question and the answer. PMOS reads the record and answers with a note.
-
-To fix the topic, press **Topics**. Press **Not this topic** and pick the topic the room is on, or press **Something new**. **Park it** moves the room to the next topic it has not covered. **Add topic** adds a topic. PMOS starts the topics from the steps of the meeting, then adds topics that come up in the talk. Topics have no time limits.
-
-The companion starts only while the meeting is recorded. It reads the new lines of the transcript at most every 40 seconds. It writes the sentence, the chips, the topic and the notes. If the answer is not usable, PMOS drops it and shows nothing. To stop the companion, set `PMOS_FOCUS_AGENT` to `off`. The page then shows the transcript and a quiet line, and it adds no notes. In the last 5 minutes, and after the meeting, the page shows the captured items under the material. You confirm them in the note after the meeting. Nothing goes to other people.
-
-### Meeting material
-
-Link the documents, reports and decks that you want to show or present in a meeting. The card of a meeting that has not ended has a **Material** part. It lists each linked item with its kind, the topic it is for, where it came from (the invite, the morning brief, or you), and whether it is for this meeting or for every meeting in the series. Each item has **Present** or **Open**, and a remove button (x). Items from the invite and the morning brief have no remove button. PMOS keeps your items in its own record (`meeting-material.jsonl` in the runtime folder). It does not change your calendar invite. Removing an item does not change the document.
-
-Press **Add material** to open the sheet:
-
-- **Suggested for this meeting**: the documents of the level of the meeting (the initiative it is about) and the newest reports and decks, with the reason for each.
-- **Find in PMOS**: type two letters or more to search the titles of documents and report decks.
-- **Or paste a link**: a Google Slides, Google Docs or Confluence link, or any https address. A web page opens in a new tab. PMOS does not read it.
-
-After you pick an item, choose **For** (this meeting, or every meeting in the series), **Topic** (one of the topics of the meeting, or the whole meeting) and **You** (**Present it** or **Only read it**, for a PMOS deck or a Google Slides link).
-
-In **Focus**, the material shows next to the links of the invite. An item for a topic comes up on the stage when the room is on that topic. When the room moves to another topic, the stage goes back to the first link. Press an item in the **Material** switch to keep it on the stage. A PMOS deck or report opens in PMOS. A PMOS deck has **Present**, which opens the presenter view with your speaker notes, and **Audience view**, which opens a window of its own with the slides only. Drag that window to the screen or the projector that you share. In the presenter view, the window follows your slide, and a key in the window moves your slide. Closing the presenter view closes the window. If the browser blocks the window, a notice says so and **Full-screen view here** shows the slides full screen in this window. A Google Slides deck opens in its own tab, as before. When nothing is linked, the Material part of Focus has **Add material**.
-
-### Meeting focus over Google Meet
-
-The PMOS Chrome extension shows a small panel over a Google Meet call, so you do not need to switch to the PMOS tab. The panel is the Meeting focus page in a compact form. It has a head with the topic the room is on (or "Starts in" before the start) and the time left, the **What's being said** line, the conversation with PMOS, and **Ask PMOS quietly**. Only you see it. It is not part of the screen you share. The extension reads the address and the title of the Meet tab only. It does not read the call's audio or captions, and it talks only to the PMOS on your computer.
+The PMOS Chrome extension shows a small panel over a Google Meet call, so you do not need to switch to the PMOS tab. The panel is a compact meeting focus. It has a head with the topic the room is on (or "Starts in" before the start) and the time left, the **What's being said** line, the conversation with PMOS, and **Ask PMOS quietly**. Only you see it. It is not part of the screen you share. The extension reads the address and the title of the Meet tab only. It does not read the call's audio or captions, and it talks only to the PMOS on your computer.
 
 To add the extension:
 
@@ -183,41 +22,3 @@ To add the extension:
 PMOS must run while you use the panel. The extension looks for PMOS at `http://localhost:7433`. If `pmos` started on another port, open the extension's **Options**, type that address and press **Save**, then reload the Meet tab.
 
 To use it, open a Meet call. The panel shows at the bottom right of the call, and not on the Meet home page. PMOS finds the meeting on your calendar by the Meet link in the invite. If no invite has that link, it uses the title of the tab, and then the meeting that is under way now (from 10 minutes before the start to 10 minutes after the end). If none fits, the panel says "No meeting right now" and lists today's meetings. Press the one this call is. **Fold** shrinks the panel to a pill that shows the head only, and the same button opens it again. **Open focus in PMOS** opens the full Meeting focus page in a new tab, with the material, the topics and the captured items. If PMOS does not answer, the panel says "PMOS is not running at" and the address, with a link to the Options.
-
-## Free time
-
-Press **Free time** to show the free blocks. A free block is a gap inside your working hours that is long enough to use. On Day and Week, each block is a dashed purple window on the timeline, with its length, for example "1.5 h focus". The side column lists the blocks, up to 8, with the suggestion for each. On Month, Quarter and Year the list says that free time shows in the Day and Week views, and the chip still shows the number of blocks.
-
-Each block can have a suggested use, for example a prep step that is at risk or the top item due that week. When nothing fits, the block says "Free, nothing specific to suggest". A suggestion is only a proposal. PMOS writes nothing to your calendar.
-
-## Tidy-up
-
-Press **Tidy-up** to see what to change in the calendar of the range. The chip shows the number of suggestions. PMOS finds them with fixed rules. It does not use a model.
-
-| Rule | When PMOS raises it | Severity |
-|---|---|---|
-| Overlap | Two meetings with a time overlap. | Needs a fix |
-| No break | A meeting starts less than 10 minutes after the one before it ends, on the same day. | At risk |
-| Prep at risk | A coming meeting has prep steps left, and less than 30 minutes of free time remain before it for each step. | At risk |
-| Stopped initiative | A meeting is about an initiative that is done, parked, on hold, closed or cancelled. | At risk |
-| Review too early | A review, sync or checkpoint comes before a milestone or promised date of its initiative that is not done. | Worth a look |
-| Late initiative | A milestone or promised date in the range belongs to an initiative that is delayed, overdue or at risk. | Needs a fix when delayed or overdue, At risk when at risk |
-| Heavy day | A working day has more than 6 hours of meetings. | Worth a look |
-
-All-day events take no time, so the time rules do not use them.
-
-The side column lists the suggestions in three groups: **Needs a fix**, **At risk** and **Worth a look**. Each suggestion tells you why PMOS raised it and proposes one change, for example "Move Design sync to 10:30 or shorten Standup." The links under it open the items involved: a meeting link shows the meeting in the detail, and an initiative link opens the initiative in Initiatives.
-
-On Day and Week, each meeting that a suggestion names has a coloured ring. Red means Needs a fix. Amber means At risk.
-
-A suggestion is only a proposal. PMOS has no access to your calendar and changes nothing. You make the change in your calendar or where the item lives.
-
-When the range has no suggestion, the list says "Nothing to tidy in this range." When a rule cannot run, for example because no calendar is imported, the list names the rule under **Not checked** and tells you why. When the server sends no tidy-up list, the list says so.
-
-## Empty states
-
-The **In this range** list in the side column names each layer with its count. When a layer is empty, it tells you why. For example, no calendar is cached yet, or the server sent no dated items. When the range has nothing at all, the grid says so.
-
-On a narrow screen the side column is under the grid. From 1100 pixels wide it is at the right.
-
-Each suggestion has two buttons. **Propose it** marks it as proposed and shows a note that nothing changed in your calendar. **Dismiss** hides it for the rest of the visit. Neither button changes your calendar or sends anything to anyone.

package/workspace/guide/data-freshness.md

@@ -1,7 +1,7 @@
 ---
 type: Guide
 title: "Data freshness: how the workspace keeps up to date, and how old each source is"
-timestamp: 2026-11-03
+timestamp: 2026-11-04
 ---
 
 # Data freshness
@@ -55,7 +55,29 @@ The Sources list shows them as one row, **Your tools**. Its time is the oldest r
 
 ## Refresh all: the sources first, then the Briefing
 
-On Home, the Board and Intelligence, the sources list is in **Settings › Connectors**. There is no Sources card in the place menu. Each source shows when PMOS last read it. A source that is old or failed has an amber dot and ↻: press ↻ to read it again. ↻ in the Connectors header is **Refresh all**. While a source is old, an amber box at the top of Settings names it, and the place menu opens Settings at Connectors.
+On Home, the Board and Intelligence, the sources list is in **Settings › Connectors**. There is no Sources card in the place menu. Each source shows when PMOS last read it. A source that is old or failed has an amber dot and ↻: press ↻ to read it again. ↻ in the Connectors header is **Refresh all**. When a source needs you, an amber box at the top of Settings names it, and the place menu opens Settings at Connectors. Claude repairs the other problems by itself, so you do not see a box for them (see below).
+
+## When a source cannot be read: Claude repairs it first
+
+You do not need to watch the sources. When a source that is on is past its limit, never read, or its last read failed, Claude reads it again by itself, without a press. Calendar, Jira, My work, tracker items and Your tools are each repaired this way.
+
+1. The first repair starts at once. The next ones wait 2, 10, 30 and 120 minutes. After a rate limit they wait 15, 60, 120 and 240 minutes. Claude tries at most 5 times. A repair waits while a read of that source is already going, in your quiet hours, and while the run limit is reached.
+2. After each try, Claude finds why the read failed: the sign-in of the connector expired, the connector is not connected or did not start, the network or the proxy did not answer, the tool asked to slow down (rate limit), Claude is signed out on this computer, or the skill stopped with an error. A read that ends but saves nothing new also counts as a failure.
+3. Each try is a line in the refresh log, with the trigger **repair** and a note such as "Repair 2 of 5: the last read failed because the network or the proxy did not answer".
+
+While Claude repairs a source, the source row says **Reading again** with its amber dot, because its data is still old. There is no amber box. When a read proves that the source is up to date, the row shows its new time. PMOS says a source is up to date only when a read proved it.
+
+The amber box shows only when you must act. It names the one action, links to the place where you do it, and says what Claude already tried. For example: **Reconnect Jira.** Jira was last read 3 days ago because its sign-in has expired. Board and the Jira-linked initiatives may be out of date. Claude read it again 2 times since 07:02.
+
+| Why | When the box shows | The action |
+|---|---|---|
+| The connector is not connected | after the first try | **Connect** the source in your Claude connectors (claude.ai/settings/connectors) |
+| The sign-in of the connector expired | after the same failure twice | **Reconnect** the source in your Claude connectors |
+| Claude is signed out on this computer | after the same failure twice | **Sign in to Claude** in Settings › Claude (Terminal: run `claude`, type /login) |
+| The network, a rate limit, a connector that did not start, or a skill error | after 5 tries | ↻ **Read it again** |
+| The source is read only when you press Refresh | at once | ↻ **Read it again** |
+
+The box also adds one item to Needs you, once. The schedule keeps running while the box shows, so after you fix the connection the next read clears the box. A source that you switched off is not repaired and shows no box. Its row still says how old it is.
 
 **Refresh all** in Sources is one run, in a fixed order:
 
@@ -106,7 +128,7 @@ A refresh waits for the sources it uses. The briefing waits for work assigned to
 
 - **Catch up**: a refresh missed while PMOS was closed runs once when PMOS starts. Off, the missed slot is skipped and written to the log.
 - **Retry**: a failed scheduled refresh is tried once more after 15 or 60 minutes.
-- **Tell me**: a failed scheduled refresh adds one item to Needs you on the Briefing.
+- **Tell me**: a failed scheduled refresh adds one item to Needs you on the Briefing. While Claude repairs that source, the repair adds the item instead, once, and only when you must act.
 - **Runs at once**: at most this many scheduled refreshes run together. A refresh you press is never held.
 - No scheduled refresh starts in your quiet hours; the background jobs keep to the day check's working hours.
 - **Deep work runs at night or when you step away.** Your impact, metric drafts and reads, Claude's morning checks of initiatives, and core document drafts run between 01:00 and 05:00. If PMOS was not running then, they run when you have not pressed anything or typed in a terminal for 30 minutes. Quiet hours hold them too. Each one still runs at most once a day.
@@ -120,4 +142,4 @@ A refresh waits for the sources it uses. The briefing waits for work assigned to
 
 ### The refresh log
 
-Every background run is written to `refresh-log.jsonl` in your runtime folder on this computer: a start line and an end line with the result, the time it took, what it got and the error. A skipped slot writes a line with the reason. The start line records each input's state and when it last refreshed. A done refresh of Jira or of work assigned to you keeps a copy of what it read, so you can see what PMOS knew at any time. Lines and copies older than the keep setting (30, 90 or 365 days, or forever; 90 by default) are removed once a day. The log view filters by source and result, and **Export** downloads it as CSV.
+Every background run is written to `refresh-log.jsonl` in your runtime folder on this computer: a start line and an end line with the result, the time it took, what it got and the error. A skipped slot writes a line with the reason. The start line records each input's state and when it last refreshed. A done refresh of Jira or of work assigned to you keeps a copy of what it read, so you can see what PMOS knew at any time. Lines and copies older than the keep setting (30, 90 or 365 days, or forever; 90 by default) are removed once a day. The repair of each source is kept in `source-heal.json` next to the log: each try, its time and why it failed. The log view filters by source and result, and **Export** downloads it as CSV.

package/workspace/guide/docs.md

@@ -1,137 +1,22 @@
 ---
 type: Guide
-title: "Docs: every repository file by category, the files each one links to, and whether each copy in Google Docs or Confluence is the same"
-timestamp: 2026-10-07
+title: "Documents and their Google Docs and Confluence copies"
+description: "Where documents open in the workspace, how the Viewer shows a Google Docs or Confluence copy of a file, and the pmos docs commands."
+timestamp: 2026-11-03
 ---
 
-# Docs
+# Documents and their Google Docs and Confluence copies
 
-Open Docs from the top bar, from ⌘K (**Docs**), or press `g d`.
+A document opens as a page in the Viewer. Find it with Search (⌘K), or open it from an initiative's **Documents**. [Home](home.md) explains the document page: **Page**, **Edit** and **Markdown**, the edit log and the agent's proposals.
 
-Docs lists every markdown file in the repository by category. For each file, it shows the files that it links to and the files that link to it. For each document that has a copy in Google Docs or Confluence, it shows whether the repository version (PMOS) or the copy is newer. You can then use one version over the other, one copy at a time.
+## A copy in Google Docs or Confluence
 
-Nothing syncs by itself. A copy changes only when you press a button for that copy.
-
-## The list
-
-The title at the top says how many copies need you, for example "2 need you in pmos". The three views are a segmented control at the top right, each with a count. Under the title, one bar shows when the copies were last compared, a search box and the **Compare every copy again** button. The list is in one card with a small label that names the view.
-
-Docs has three views:
-
-- **Needs you** shows the copies that are not the same.
-- **With a copy** shows every copy.
-- **All files** shows every markdown file in the repository.
-
-The copies are grouped by category.
-
-## Categories
-
-The category of a file comes from its folder, then from its frontmatter `type`. You do not tag a file.
-
-| Category | Files |
-|---|---|
-| Specs | `planning/prd/`, or `type: PRD` |
-| Initiatives | `planning/initiatives/` |
-| Decisions | the ADR folder, `DECISIONS.md`, `pm-decisions.md` |
-| Research & plans | the other `planning/` folders |
-| Explainers | `planning/explainers/` |
-| Evals | `planning/evals/`, or `type: Rubric` |
-| Knowledge | the other `okf/` folders |
-| Guides & rules | all other files |
-| Prototypes | `prototype/` |
-
-## All files
-
-**All files** opens with one line for each category: its name, its number of files, and "N need you" when a copy in it is not the same. Press a category to open it. It shows its first 20 files: the files with a copy first, then the newest. Press **Show all** to see the rest.
-
-A file with no copy is one line: its title, the short name of its initiative (or its path when no initiative owns it), and the date of its last edit. **Add copy** shows when you point at the line, and always on a touch screen.
-
-## The links of a file
-
-Press a file in **All files** to see its links:
-
-- on the left, the files that link to it;
-- in the middle, the file;
-- on the right, the files that it links to.
-
-Each side shows at most 7 files. A dashed line is a decision that the file cites. Press a file in the graph to put it in the middle. Press **Back** to go back. **Open file** opens the file in the reader.
-
-**List all N links** lists every link in both directions, grouped by kind.
-
-A link counts only when a file writes it:
-
-- a markdown link to another file;
-- a path in the frontmatter, such as `prd_path`;
-- the `initiative_id` of the file;
-- the anchor (`parent_kr`);
-- a decision number, such as D65.
-
-PMOS does not guess a link from similar words. `pmos kg neighbors <path>` shows the same links in the terminal.
+A repository file can have a copy in Google Docs or Confluence. The Viewer shows a copy from what PMOS has recorded. PMOS does not read either tool when the page opens.
 
-On a phone the graph is not shown. The list is shown.
+- **A copy linked to a file.** When the last check found the same text, the Viewer shows the file as the copy's text. When the copy changed, the Viewer shows the file dimmed and labelled as the PMOS version, with **Use the copy's version** and **Check again**. Use the copy's version can be undone for five seconds.
+- **A page PMOS only links to.** The Viewer shows the last read of the page, if there is one. **Read it now** starts one read-only session that reads the page with your connector and keeps the text. Nothing is written to the tool.
 
-Each copy is one line:
-
-- a status dot;
-- the document title, and a link that opens the copy in a new tab;
-- one sentence, for example "PMOS is newer · You, today 09:12";
-- at most one button.
-
-| Sentence | Means | Button |
-|---|---|---|
-| Same | The last compare found the same text, and neither side changed since. | none |
-| PMOS is newer | The repository file changed since the two sides last matched. The copy did not. | Use PMOS version |
-| Confluence is newer (or Google Docs) | The copy changed since the two sides last matched. The repository file did not. | Use Confluence version |
-| Edited on both sides | Both changed since the two sides last matched. | Choose… |
-| Not compared yet | No compare has read the copy. | none |
-| Can't open in Confluence | The compare could not read the copy. The reason is shown. | none |
-| Not found in Confluence | The copy is deleted or in the trash. | none |
-| Not in PMOS any more | The repository file is not there. | none |
-| Sync failed | The last sync of this copy wrote nothing. The reason is shown. | as before the sync |
-
-"by date" after a sentence means that the two sides have never matched. The newer modified date then decides.
-
-Frontmatter is not part of the text. A change to the frontmatter only does not change the sentence.
-
-## The details
-
-Click a line to see its details:
-
-- **PMOS**: the repository path and its last edit;
-- the copy: its address and its last edit;
-- a **Use … version** button for each side;
-- the first difference that the compare found, when it found one;
-- **Compare again** and **Stop tracking this copy**;
-- the links of the file, as in **All files**.
-
-**Stop tracking this copy** removes the link. The copy is not deleted. Press **Undo** in the message to link it again.
-
-## Use a version
-
-**Use PMOS version** writes the repository text to the copy. **Use Confluence version** (or Google Docs) writes the copy's text to the repository file.
-
-1. Press the button. The line says "Updating Confluence…" and a message shows **Undo**.
-2. To cancel, press **Undo** within five seconds. Nothing is changed.
-3. After five seconds, PMOS starts a session with the `doc-sync` skill. The session writes one side only, with your own Google Drive or Atlassian connector. If PMOS asks you to allow the write, allow it in the session.
-4. When the session finishes, the line says **Same**.
-
-A sync never creates, moves or deletes a page or a file. When the copy's text is written to the repository file, the file's frontmatter stays as it is. The session does not commit: use Sync in the bar to commit and push the change.
-
-## Compare
-
-PMOS cannot read Google Docs or Confluence itself. **Compare every copy again** in the bar, next to "Compared … ago", starts a session that reads every copy with your own connectors. The session reads only. The sentences change when it finishes.
-
-A compare runs only when you press it. There is no schedule. An edit to a repository file changes its sentence at once, without a compare.
-
-## Add a copy
-
-Type in the search box. The search finds every markdown file in the repository by its title, its path or the name of its initiative, also files that have no copy. The results are grouped by category, and the match is marked. Press Esc to clear the search.
-
-Press **Add copy** on a file with no copy.
-
-Press **Add copy**, paste the address of the Google Doc or Confluence page, and press Enter. A document can have one Google Doc and one Confluence page.
-
-A link that you add in an initiative's artifacts is the same link and shows here too.
+Nothing syncs by itself. A copy changes only when you press a button for that copy.
 
 ## From a terminal
 

package/workspace/guide/home.md

@@ -1,13 +1,13 @@
 ---
 type: Guide
-title: "Home (/premium.html) and the designed features"
-description: "Home in the Agreed design: the list grouped by product, the Viewer, the place menu, Your day and its New for you fold, Search, and the initiative, meeting, report, Board and Insights features designed after it."
+title: "Home: your list, the chat and the Viewer"
+description: "Home: the list grouped by product, the Viewer, the place menu, Your day and its New for you fold, Search, and the initiative, meeting, report, Board and Insights features designed after it."
 timestamp: 2026-11-03
 ---
 
 # Home
 
-Home is the page at `/premium.html`. It follows the Agreed design and the "Uncovered features" canvas (initiative `premium-uncovered-features`). The left side is one list. The middle is the chat. The right side is the Viewer. A row opens its item in the Viewer. On a phone the list is the page, and a row opens its conversation with a back bar.
+Home is the page PMOS opens on. The left side is one list. The middle is the chat. The right side is the Viewer. A row opens its item in the Viewer. On a phone the list is the page, and a row opens its conversation with a back bar.
 
 Home, the Board, Insights and the Viewer use one typeface, Plus Jakarta Sans, with two weights (regular and semibold) and four sizes: 13, 15, 18 and 26 px. Each kind of text has one role, and the role sets its size, weight and line height: a large number and a page title are 26 px, a panel title is 18 px, a group head, a row's name and a sentence are 15 px, and the quiet meta line, a label and a badge are 13 px. The same kind of text looks the same on every page. Rows have room to breathe, so a list row is about 52 to 58 px high. There is no compact setting. Slides and report templates keep their own sizes.
 
@@ -153,8 +153,9 @@ Claude names a session after its first real answer. It does not ask. It changes
 
 Some features are still not designed. Home keeps each one usable as a plain card in the Viewer with the label **Waiting for design**. The label means that the card works, but its look is not final.
 
-## Search and Settings
+## Search, Guide and Settings
 
+- **Guide** (the **?** icon in the menu) opens this guide in the Viewer.
 - **Search** (Ctrl K or ⌘K, or `/`) finds initiatives, documents, sessions and files in the repository and its worktrees.
 - **Settings** holds the workspace settings. **General** holds the theme (Light, Dark or Auto). **Connectors** shows when PMOS last read each source. A source that is old or failed has an amber dot and ↻ to read it again. ↻ in the Connectors header reads every source again. While a source is old, an amber box at the top of Settings names it, with ↻.
 
@@ -168,7 +169,9 @@ Some features are still not designed. Home keeps each one usable as a plain card
 
 ## The place menu
 
-Press the round button at the bottom of the page (bottom left on a desktop, bottom right on a phone). The menu lists **Home**, **Board** and **Intelligence**. Under them are two icons: **Search** (⌘K on a desktop) and **Settings**. The menu holds nothing else.
+Press the round button at the bottom of the page (bottom left on a desktop, bottom right on a phone). The menu lists **Home**, **Board** and **Intelligence**. Under them are three icons: **Search** (⌘K on a desktop), **Guide** and **Settings**. The menu holds nothing else.
+
+- **Guide** opens this guide's start page in the Viewer of the page you are on. A link to another guide page opens it in the same place; ← goes back. The guide opens wide: every page in a list on the left, by group, with Find a page; a chip for each section above the page. On a phone the list icon beside the title shows the list. The address `/premium-viewer.html?open=guide&page=<name>` opens one page on its own.
 
 - The button has a blue dot when something is new for you, and an amber dot when a source is old. The dots show on every page. When the menu is open, the blue dot is on **Home** (New for you is in Your day) and the amber dot is on **Settings**.
 - When a source is old, **Settings** opens at **Connectors**, with the old source first.