vibe64 0.1.32 → 0.1.34

package/docs/colleague-usage/connected-contributions.md

@@ -0,0 +1,196 @@
+# Connected contributions and saving
+
+This continues [Configure connected projects](connected-projects.md): how prepared sources become contributions, how they are saved, revised and integrated.
+
+Preparing a connected source records the creating user's Git identity for that
+receiving session. You can inspect and save its contribution without first
+opening an AI conversation there. GitHub access is still checked when used.
+
+A connected session takes the name of the session it was prepared for: that
+session's name, or its date when it has none yet. When the originating session
+is renamed, its connected sessions follow at the next workspace preparation. If
+you rename a connected session yourself, it keeps your name.
+
+Allocating a connected contribution creates its receiving checkout without
+automatically preparing that receiving project's own connections. The originating
+project's Stack recipe prepares its directly connected sources. This prevents
+automatic chains and cycles of extra contribution checkouts. A receiving session
+can still be prepared separately when you deliberately work in that project.
+If project A connects to B and B connects to A, preparing B's contribution creates
+a new A contribution; it does not attach the original A session. Each preparation
+owns its child contributions, and retry reuses those children. You cannot use
+these controls to make two existing contributions wait for each other. Split a
+shared library change from its consumer adaptation when they need separate
+acceptance steps.
+
+A connected contribution session saves to its own receiving-repository branch,
+shown in the normal Save destination review. Its first Save creates that branch;
+later Saves update the same contribution. The receiving project's main branch
+is unchanged. Contribution submission does not require creating a pull request,
+but the receiving repository's branch permissions still apply.
+
+If the contribution was discarded, further work needs a new contribution. If both
+active and discarded branches exist, resolve the interrupted discard first. A
+missing branch after a publication attempt needs its retained exact revision and
+receiving history checked; its absence alone proves nothing. An integrated
+revision remains accepted after its branch is discarded or deleted. Explicit
+Update can consume the proven accepted source, but further contribution pushes
+cannot recreate that removed branch. Keep the checkout and ask the coding agent
+to inspect uncertain saved work. After a lost acknowledgement, existing Save recovery can reconcile a
+publication when the remote confirms its exact prepared commit.
+
+To revise a discarded, unmerged contribution, return to the originating session
+and press Save. Its refusal offers **Review replacement contribution**. Review
+the repository, integration target and exact discarded commit, then choose
+**Create replacement contribution**. The same controls are available on phones.
+This creates a new receiving session and contribution ID, selects it for this
+originating task and updates the development source map. It does not push anything.
+Use **Open replacement session** to revise that source.
+
+The replacement starts at the discarded commit. The old checkout, including
+unsaved edits, remains intact; copy any wanted unsaved edits into the replacement
+explicitly. The discarded branch remains available in Incoming changes. Old
+submitted revisions remain integration requirements, and the replacement retains
+their ancestry. Removing a connection or creating a replacement does not unblock
+Main Save by itself.
+
+After editing, run **Prepare workspace** in the originating project and restart
+Preview so it uses the replacement. Use **Save connected first** to submit the
+revision, merge it through the receiving project's Incoming changes, and Update
+the replacement session to the accepted target before Main Save. If creation's
+response is lost, retry the same confirmation: it reuses the reserved replacement.
+After reloading or closing that dialog, **Prepare workspace** also resumes the
+saved reservation. A changed review, revoked access or unavailable source stops
+preparation with an error and preserves both sources. Colleague can review and
+create a replacement through the same actions after an explicit request; it
+cannot silently discard or move unsaved edits.
+
+## Keeping connected repositories current
+
+Each workspace preparation of the consuming session also brings every connected
+checkout up to the latest commit of its integration branch. That happens when
+the session is created, after **Update this session (rebase)** and on **Prepare
+workspace**. A session with connected repositories also shows **Update connected
+repositories** in its session actions menu (**⋮** on a phone or narrow window).
+It runs the same preparation.
+
+The update uses the receiving session's normal **Update this session (rebase)**,
+which carries that checkout's own changes, including unsaved edits, onto the
+branch's latest commit. A checkout is left as it is while its agent is working,
+while a Save or Update runs in it, while its published contribution still awaits
+acceptance, or when the update would conflict with its changes. The preparation
+output shows one line per repository: `[Connected] jskit updated to abc1234.`,
+`[Connected] genesis is up to date.`, or `[Connected] vibe64 was not updated:`
+followed by the reason. A conflict is recorded in the receiving session for review;
+open that session in the receiving project to resolve it. Preparation continues
+either way, and an updated checkout is prepared again before the consuming
+session links it. Choose **Update connected repositories** again once the cause
+is resolved. Colleague can run this preparation for the session on request and
+report each line; it does not resolve a skipped checkout's work.
+
+Main Save and pull-request creation check each connected repository's branch
+live. If a connected checkout is behind, they stop with `<repository> is behind
+<branch> by N commits. Choose Update connected repositories, check your work,
+then Save.` This keeps saved and deployed work tested against the current
+connected sources.
+
+When a session has recorded submitted contributions, its normal Save checks those
+exact revisions before publishing, including when the main repository has no new
+file changes. If one is still pending, the error names the receiving repository,
+contribution, revision and integration branch. Once all are accepted and the
+selected sources are reconciled, a clean main repository reports no work to save. Open that
+receiving project's **Incoming changes**, review and merge the contribution, then
+open its connected contribution session and use **Update this session (rebase)**
+to incorporate the accepted receiving source before retrying Main Save. This
+matters when merge conflict repairs changed the accepted code. Save never performs
+that update automatically. Discarding it or removing its connection does not satisfy the check.
+An access or incomplete-history error requires fixing that cause and retrying;
+Vibe64 does not infer a merge from a missing branch or a similar diff.
+
+After a receiving contribution session completes normal renewal, connected
+preparation and Save use its confirmed successor while retaining the same
+contribution branch and integration requirements. An unfinished, missing or
+mismatched handover blocks access instead of falling back to archived source.
+Complete or recover the renewal in the receiving project, then run **Prepare
+workspace** and restart the originating Preview to consume the new source path.
+
+Archiving the originating session does not archive its connected sessions or
+delete their incoming branches. Each receiving session has its own lifecycle.
+Use **Stop preview** when you only want to stop a dependency's running app; this
+keeps its source available to the originating project.
+
+Avoid archiving a receiving contribution while another session still needs its
+checkout. Archive preserves its commits, changed files, untracked files and
+connection metadata through the existing recovery archive, then removes the live
+checkout. The originating project reports unavailable source; it does not select
+a different session or silently use an npm package. Use normal renewal when you
+want a fresh conversation that continues the same contribution. If already
+archived, retain the archive and ask the administrator to recover its source
+through the existing archive facilities before preparing the originating project
+again. Colleague can explain the error; it cannot substitute another checkout or
+clear the integration requirement to make Save succeed.
+
+After integration, the contribution session's existing update check follows the
+receiving integration branch. Its Save destination remains the reserved incoming
+branch; later edits become another contribution there. Main Save requires the
+accepted target in the connected source's history, so a newer receiving target
+can require another explicit Update. Rerun the originating project's workspace
+preparation when its connected outputs need rebuilding, then verify the app.
+
+A newer submitted revision needs its own integration. Later unrelated work on
+the contribution branch does not block a revision already merged. Colleague can
+explain a Save refusal and offer the supported receiving action, but must obtain
+an instruction to merge or discard.
+
+For prepared sources, the chat Save button changes to a branch icon labelled **Save connected
+first** when connected work needs submission. It remains available when the main
+checkout has no changes. Its confirmation lists receiving repositories and
+contribution branches. Choose **Push connected contributions** to publish those
+changes; the main project's changes stay local. The same controls work on phones.
+The result lists confirmed pushes, including those completed before a later
+failure. Review them in each receiving project's **Incoming changes**.
+
+Once connected work is submitted, the button returns to its ordinary Save
+appearance. Pending integration does not disable it: clicking reports the
+receiving contribution that must be merged. New connected edits restore **Save
+connected first**. A main-project PR policy does not require a PR for submitting
+these contribution branches.
+
+Colleague and API clients use the existing
+work inspection and Save actions. When inspection returns
+`connectedSaveRequired: true`, review every `connectedReview` destination and
+pass that list unchanged with the main `destinationReview` to Save.
+
+This saves one connected repository at a time: commit, push, record its commit,
+then continue. It never pushes the main project in that action. A failure reports
+the completed repositories and the repository that failed. Inspect and retry:
+completed repositories without new changes are skipped. If publication succeeded
+but recording failed, retry records the confirmed receiving commit without
+republishing it. These commit records identify required integration, not a
+separate retry ledger. Files and existing receiving Save recovery remain available.
+Each receiver is checked again when its turn arrives, so new edits made while
+an earlier repository was saving are included in the next receiver's Save.
+If a push loses its acknowledgement, the exact remote commit can confirm it.
+If the remote is unavailable too, publication stays unknown: restore repository
+access and inspect work again. Recovery checks the original prepared commit
+without another push, including after restarting the editor. Main Save remains
+blocked while that outcome is unknown.
+The same recovery checks a failed local update after a push. When Git proves
+the attempt did not publish, its original rejection remains visible. A receiving
+project with its own connected work must satisfy its own Save checks; this action
+does not recursively publish further repositories.
+If preparation fails before any push is attempted, fix the reported cause and
+retry; the contribution's files and recovery checkpoint remain. A missing branch
+after an uncertain push is still unknown, so Vibe64 does not recreate it merely
+because it is absent.
+
+After connected work is saved, omit `connectedReview` for ordinary Main Save.
+Pending integration is reported by the existing exact-revision gate. New connected
+work or unreconciled publication blocks Main Save; inspect and save/recover the
+receiving session first. Colleague must review these destinations and have an
+explicit Save instruction before publishing.
+Main Save checks those sources again after preparing its commit, immediately
+before pushing. If a receiving worktree, HEAD, or recorded saved commit changed,
+inspect connected work and save it before retrying. This is a final snapshot
+check, not a lock across projects; avoid editing connected sources while Main
+Save is publishing, because changes after the final read belong to later work.

package/docs/colleague-usage/connected-projects.md

@@ -0,0 +1,196 @@
+# Configure connected projects
+
+If a receiving repository's status cannot be checked, the ordinary Main Save
+control remains available. Save checks access and state again and reports the
+blocker without pushing the main project. An unavailable status does not count
+as a merged contribution.
+
+Checking connected Save status can take longer on a busy development workspace
+because it checks each receiving repository. Allow up to two minutes for the
+check. If status remains unavailable, use Save to check again and read its
+reported blocker; an incomplete check never publishes the main project.
+
+The session badge shows **Unsaved changes** when a connected repository needs
+publication, even if the main repository is clean. After connected Save succeeds,
+the result lists the pushed commits. An empty progress card closes when the action
+finishes; opened details with real output remain available until dismissed.
+
+Open the intended project and session, then **Dashboard → Project settings →
+Connected projects**. On phones, use **Show project** and **Dashboard section**
+to reach Project settings. The list belongs to the displayed source checkout.
+
+`vibe64.connections.json` is the only repository connection list. If it does not
+exist, use **Add project**, then **Save connected projects** to create it. You can
+also edit this tracked source file directly. Stack contains technology and generic
+placement/treatment instructions, never repository identities or initial lists.
+Opening Settings and preparing a workspace do not create or import this file.
+
+For concurrent hosted tasks, configure each receiving project's **Project settings
+→ Development database → A separate database for each session** before opening
+its sessions. **One database shared by this project** permits only one open
+session unless **Allow multiple sessions with this shared database** is enabled,
+including connected contributions and libraries with no database. With project
+scope already selected, enable the override and choose **Save database choice**
+without closing work; all sessions share data and the ordinary three-session cap
+still applies. Then use workspace preparation **Retry**. Disabling the override
+preserves existing sessions but blocks additional creation. Preparation never
+archives existing work or changes this preference for you.
+
+For each entry, provide a **Name**, a **GitHub repository URL**, and a
+**Relationship**: Dependency for a library or tool; Composition for source
+assembled into this project. Use an HTTPS URL without credentials. The same
+repository cannot appear twice under different names. More projects can be
+added later, up to 64 entries within a 64 KiB file. Oversized saves preserve the
+current list; shorten the entries before retrying.
+
+**Package type** is separate from Relationship. Choose **Stack default** to
+inherit the consuming project's `Default package type`, or override it for this
+connection with **npm (Node.js)**, **Composer (PHP)**, **pip (Python)**,
+**Bundler (Ruby)**, **Go modules**, **Cargo (Rust)**, **Maven**, **Gradle**,
+**NuGet (.NET)** or **custom**. The file stores `npm`, `composer`, `pip`,
+`bundler`, `gomod`, `cargo`, `maven`, `gradle`, `nuget` or `custom`. Stack
+default leaves `type` out of the file, so a later Stack default change still
+applies.
+
+Each language's Stack proposes its default: Node `npm`, PHP/Laravel
+`composer`, Python `pip`, Ruby `bundler`, Go `gomod`, Rust `cargo`, Java
+`maven`, Kotlin `gradle` and C# `nuget`; C/C++ and shell projects use `custom`.
+A multi-language project's own `Connected development` section chooses one
+default; override other connections individually. A type other than custom is a
+declared label, not an installer: Vibe64 never runs Composer, pip or any other
+package manager because of it. The consuming project's declared Prepare and
+Verify commands read the type from the prepared source map and give the source
+that ecosystem's treatment. Every such type requires at least one Verify command.
+
+For **custom**, provide **Preparation script (project-relative)**, for example
+`tooling/prepare-native-worker.mjs`. The script lives in the consuming project;
+use a relative path outside `.git`, without `..`, absolute paths or backslashes.
+Stack declares the script runtime and runner, for example:
+
+```markdown
+- Custom runner with `nodejs` `cpp`: `node`
+```
+
+The existing preparer appends the absolute script path, then `--phase`
+(`prepare` or `verify`), `--source-root`, `--project-root`, `--sources-file` and
+`--repository` with their values. The script must remain inside the consuming
+project; preparation rejects missing files and symlinks that escape that root.
+Only custom connections have a script. Choosing any other type disables
+**Preparation script (project-relative)** and removes the script from the draft. Stack default may retain a script for a custom default, and workspace
+preparation checks the effective type before running anything. The script must
+handle both phases: prepare makes the development artifact available; verify
+checks that the consuming app uses the selected source and exits nonzero on
+failure. Keep generated development artifacts ignored by Git and preserve
+release manifests and lockfiles. Vibe64 provides execution and failure reporting;
+it cannot infer what a custom artifact means or prove it from a zero-exit no-op.
+
+Use **Save connected projects** to write the complete list to
+`vibe64.connections.json` in the selected source. You must be the project owner
+and have write access to each receiving repository through your connected GitHub
+account. The file is ordinary project source and follows normal project Save.
+Saving this configuration does not commit, push, merge or deploy source.
+
+In the standalone editor, the local project owner can use these controls without
+a hosted account. A connected GitHub account still supplies repository access.
+
+**Remove** removes an entry from the draft. Saving that removal does not delete
+existing contribution source, branches or pending work. An empty saved list
+remains authoritative.
+
+If another edit changed the file, saving refuses to overwrite it. Review your
+draft, use **Reload saved list**, and reapply the intended edits. A malformed
+file needs repair by a coding agent or through Files; it is never silently
+replaced. Missing GitHub write access requires the correct
+connected account or repository permission. After an uncertain save, refresh and
+inspect the current list before retrying.
+
+Colleague can read this list or save explicitly requested changes
+through the same actions. It preserves unrelated entries and uses the read
+source session and revision. A how-to question does not authorize changes.
+Account login and repository permission grants remain human-controlled steps.
+
+The current configuration controls declare the connections. Source preparation,
+connected-first Save and Incoming changes are separate facilities; configuration
+success alone does not establish that those sources are ready or used by Preview.
+GitHub receiving projects expose [Incoming changes](incoming-changes.md) in
+Dashboard. This view reconstructs contributions from Git, independently of the
+originating project's connection list.
+
+For preparing sources, contribution sessions, Save connected work and integration, see [Connected contributions and saving](connected-contributions.md).
+
+Development consumption belongs to the project's Stack declarations. Those
+declarations must identify the connected source, where the task exposes it, how
+the selected toolchain builds/uses it, and how to verify that selection. This
+applies to mixed-language connections too: a Node application can use a connected
+C executable or library. Choose **custom** for that connection's **Package type**. Package type is
+independent of the consuming project's language and of relationship. **Stack
+default** omits `type` in the repository file. The prepared source map records
+the effective type of every entry. A project's commands decide how to treat each
+type; for example, Node treatment requires a package manifest and excludes
+custom entries even if they contain one.
+Custom sources remain available to the project's build and execution commands. For a C program those commands must build it, expose its development
+executable or library to the app, and verify the app uses that build. It need
+not appear in `node_modules`. A cloned repository alone does not establish that
+Preview or tests use its changes.
+Use the existing **Prepare workspace** action (or its **Retry** action after a
+failure). When Stack declares `Connected development`, preparation creates or
+reuses the task's authorized contribution sources, writes the declared source
+map, runs ordinary Workspace setup, then runs the connected Prepare and Verify
+commands in order. Success requires those commands to succeed. If a non-custom
+connection exists without a Verify command, preparation is blocked with
+`vibe64_connected_verification_required` ("Declare a Verify command for the
+connected pip packages."); add a Verify entry to Stack and use **Retry**. The preparation
+identity includes both recipes and the exact task source selection; changing
+that selection requires preparation again. Access is rechecked before each
+command and when checking whether preparation remains current.
+
+If a command reports that it requires an undeclared runtime, add that runtime
+to the affected command in Stack and prepare again. Vibe64 and Online's own
+Node composition checks declare both `nodejs` and `git`: Genesis inspects the
+Git worktree while verifying the composed application. Do not bypass the managed
+runtime restriction by adding host executables to PATH.
+
+The initial consumption proof covers Node.js packages through `node_modules`:
+two tasks use distinct sources, source edits reach only the intended task, and
+an ordinary release installation retains its published dependency. PHP, Python,
+Ruby, C/C++, C#, Go, Java, Kotlin, Rust and framework-specific consumption still
+need their own declared commands and end-to-end proof; choosing their package
+type only records intent. Installed language runtimes alone
+do not establish connected-source support. A declaration alone does not prove
+that Preview or tests consume the dependency.
+
+For API clients, the explicit **Prepare connected sources** operation is
+`POST /api/app/:slug/vibe64/sessions/:sessionId/connected/prepare`. It uses the
+session's configured list and requires access to each registered receiving
+project plus GitHub write access. The returned `prepared` entries identify the
+receiving project/session and report source readiness and workspace setup.
+Once every receiving source is ready, the operation writes the Stack's
+`Sources file` and returns `development.status: "inputs-prepared"`. The JSON
+file uses contract `vibe64.connected-sources.v1` and identifies the originating
+session and each connected repository's exact source path and contribution ID.
+Vibe64 excludes this generated file from Git locally; the portable connection
+list remains unchanged. The consuming project's commands can read this map,
+and **Prepare workspace** executes and verifies the complete recipe. This explicit
+API operation only prepares inputs; `inputs-prepared` does not mean its commands
+have run.
+
+The source-map location must be a development-only, project-relative file.
+Vibe64 refuses to overwrite tracked files, symbolic links, unrelated content or
+another session's map. If this check fails, preserve the file, choose another
+`Sources file` location in Stack and retry. A missing or invalid Connected
+development declaration also requires correcting Stack before retrying; the
+already-created receiving sources remain available.
+An internal readiness check can recheck receiving access and compare the map
+with the task's saved bindings without changing files. The workspace runner uses that check before running
+commands and before accepting cached preparation. `inputs-prepared` still does
+not mean the Stack's development commands have run.
+After failure or a lost response, retry the same originating session: its saved
+reservation prevents duplicate source creation. A failure retains the earlier
+`prepared` entries and identifies the receiving repository that failed. If an
+entry reports `sourceReady: false`, open that receiving session and use its
+source recovery controls before retrying; preparation does not replace the
+failed checkout with a fresh one. Missing registration requires
+setting up the receiving project first; mismatched saved authority requires
+inspection and reconciliation. Use the existing workspace preparation controls for the full recipe. Colleague
+can explain the process and offer supported preparation actions; it must not
+claim successful preparation from a declaration or an input-map response alone.

package/docs/colleague-usage/conversation-context.md

@@ -16,7 +16,7 @@ After recovery is confirmed:
 1. Reload the page and reopen the same project, session and Main chat.
 2. Read the saved reply and status. Reopening does not send another request.
 3. Select **Send** with a new continuation when ready. If an earlier request has
-   unknown delivery, use its existing **Check delivery** before deciding to resend.
+   unknown delivery, use its existing **Retry** before deciding to resend.
 
 These steps are the same on desktop and phone. Changing accounts or models is
 not a substitute for checking an uncertain request. Keep the intended account and
@@ -24,9 +24,75 @@ model unless you deliberately want to change them. If the context error returns,
 report the session and exact error to the operator rather than deleting history
 or repeatedly submitting more work. Never paste API keys into chat.
 
+Claude may show **Pending** while starting its native process after a restart.
+Keep the same conversation open and let that submission settle; a long saved
+history is not a reason to create a replacement chat. If startup fails, use the
+failed message's **Retry** after the reported problem is resolved. Colleague can
+explain the status and recovery controls on desktop and phone.
+For a recurring startup delay, give the operator the session and approximate
+send time. Startup diagnostics separate process launch, initialization request,
+completed input write and response arrival without recording the message body.
+Colleague can explain this recovery path; inspecting server diagnostics requires
+the operator's access.
+Managed Claude conversations use Vibe64's Git workflow without Claude's automatic
+startup Git snapshot or built-in commit/PR instructions. Agents can still inspect
+current changes through the ordinary managed Git tools when the task needs them;
+Save and publication keep their existing controls and permissions.
+
 Project guidance can change while Codex is working. The current turn keeps its
 installed instructions; the next idle admission reads the latest guidance without
 interrupting healthy work. Preparing that guidance does not consume the separate
 native-control timeout. If a connection error still appears, read the saved reply
 and check any uncertain delivery before sending new work; do not assume the model
 failed or repeat a request whose outcome is unknown.
+
+## Attach files
+
+Use **Add to message** or drop/paste files into the conversation. Each file may
+be up to 500 MiB. Wait for its upload to finish before sending; an oversized
+file remains marked as failed so you can remove it and choose a smaller file.
+For a directory, upload an archive through Files → Session Dropzone. Uploading
+does not itself send a message. Colleague can explain these steps; choosing a
+file from the person's computer requires their interaction.
+
+
+## Change AI while keeping the discussion
+
+In Main chat, select the intended AI with the existing assistant controls, then
+send your next message. Ordinary Claude and Codex conversations receive the
+visible discussion up to the selected destination's available normal context.
+Reasoning is excluded. This transfer keeps original message text and attribution;
+it does not create a summary or change the saved chat.
+
+If the history is too large, the oldest complete transferred messages are omitted
+first. Returning to an existing AI sends missed or corrected messages within the
+remaining allowance. The transfer reserves a small working space (5% of the
+usable window, at least 32,768 tokens) and does not enable an
+extended context window or change model settings. Carrying more history can still
+increase input usage and cost.
+
+When Claude's own memory is nearly full, Vibe64 first summarises it
+automatically — the same compaction Claude performs on its own — and then sends
+the missed messages that fit. The chat shows **Summarising the assistant's
+memory before sending…** while this happens, which can take a minute or two;
+keep the page open. Nothing in the saved chat changes.
+
+If summarising fails, or even after it there is no room left, a **Not enough
+room** dialog explains the problem and the message is not sent. Select
+**Summarise and continue** to try again, or **Close** and choose another
+assistant with the existing assistant controls. An unavailable usage reading also
+stops delivery before sending; retry after reconnecting the assistant. If a
+message instead reports uncertain delivery, use its existing **Retry**, which
+checks the original receipt without rebuilding or duplicating the request.
+These steps are the same on desktop and phone. Colleague can explain this dialog;
+selecting its buttons requires the person's interaction.
+
+This policy concerns ordinary Main chat. Learning's tool-bound context, temporary
+chat context copying and Colleague's own history policy are separate.
+
+While Claude is working, you can send a follow-up to steer the same conversation.
+Updated project guidance is applied when a later turn starts idle; it must not
+block an ordinary follow-up or restart active work. Account changes and explicit
+model settings still use their existing checks. If a message shows an error,
+keep its text and use **Retry** after the reported problem is resolved; a failed
+message does not mean Claude has stopped its previous task.

package/docs/colleague-usage/dashboard-navigation.md

@@ -2,29 +2,103 @@
 
 Open a project and select **Dashboard** beside **Preview**. The Dashboard provides
 the available session and project tools, including Files, Changes, Database,
-Subsystems, AI Terminal, Project settings, Env, App access, Integrations, Issues
+Architecture, AI Terminal, Project settings, Git log, Env, App access, Integrations, Issues
 and Pull requests. Availability depends on the selected session, host and permissions.
+On desktop the section list is grouped: tools under the **Project** label come first,
+then a **Session** label with the selected session's name and its tools. The
+highlighted pill marks the open section, and each page's header repeats that
+section's icon and title with a one-line description and its actions.
 
 On mobile, **Show project** reveals the project from chat. Use **Dashboard section**
 to choose a tool and **Back to dashboard** to return from its detail. **Show chat**
 returns to the coding conversation. Preview and Dashboard retain their own selected
 state when hidden; leaving the preview does not stop its application.
 
-Files provides **Repo** for source and **Drop Zone** for exchanging files with the
-selected session. Choose an area to browse its folders and files; searching is
+The left-arrow **Back to dashboard** control has the same appearance in
+Architecture, Current changes, Files, Database, Issues and Pull requests, including
+the same readable text size on phones. Issue actions wrap below it when space is
+limited. Use
+Tab to focus it and Enter to activate it. Files and Database opened from
+Architecture instead show **Back to Architecture**, returning to that view.
+Inside an individual issue or pull request, the same control says **All issues**
+or **All pull requests** and returns to its list.
+
+**Git log** is in the project section above the active session's tools. Open it
+to review saved commits and their file differences. **Current changes** remains
+with the selected session. If Git log offers a session update or reconciliation,
+that action applies to the selected session; opening the log does not change files.
+The same **Git log** label appears in the mobile **Dashboard section** chooser.
+
+Files provides **Repo** for source and **Session Dropzone** for exchanging files with the
+selected session, plus **Project Backups (2w retention)** shared by all sessions
+of the project. Choose an area to browse its folders and files; searching is
 optional. The workspace owner also sees the read-only **Session** area.
 Access follows the signed-in account; changing a link cannot select another role.
 Changes shows the session's source changes. AI Terminal shows the coding agent's
 native terminal; an enlarged terminal has **Exit full screen**. This leaves it
-running, while **Close terminal** stops that terminal. Subsystems presents the
-project's declared structure; asking the coding agent to investigate or update it
+running, while **Close terminal** stops that terminal. Architecture presents the UI storyboard and Engine dependency layers on one
+pannable, zoomable sheet, with registered routes on web cards; asking the coding
+agent to investigate or update it
 is separate from opening the view. Do not mistake an unavailable/loading tool for
 an empty successful result.
 
+In a practice lesson (Learning mode), **Dashboard** is this same Dashboard for the
+lesson's practice project and lesson session. It shows **Git log**, **Env**,
+**Session History** and **Health**, and the session tools **Session info**,
+**Current changes**, **Files**, **Database** and **Architecture**; all of them
+read and change only the lesson's practice project. Git log and Current changes
+are read-only there (no update, check or save buttons), Env offers no secret
+**Reveal**, and the Database Copilot and Architecture **Ask** are off. **Project
+settings**, **Integrations**, **App access**, **Incoming changes**, **Issues/PR**
+and **AI Terminal** are not shown in a lesson; opening one of their addresses
+shows **Env** instead. Moving between Dashboard sections keeps Learning mode on.
+See [Choosing lessons and Learning conversations](learning-mode-ui.md).
+
 Colleague can open supported views in your initiating browser and wait for the
 actual selection before reporting success. Ask “Show me Database for this session”
 or “Open Project settings”. It can explain visible controls using its guides.
+During an active lesson, ask it to show that lesson project's normal **Preview**
+or **Database → ERD** without leaving Learning; that project tab becomes selected and
+Main remains the teacher. The bound Main teacher can reveal the same Preview or
+ERD for its exact attempt, or—by default—point at the real tab or Dashboard section
+(Database, Files, Current changes, Git log, Session info, Architecture) with a
+short ring and caption so you click it yourself. A changed project, session, attempt or browser is
+refused instead of being silently retargeted. Agent navigation is a demonstration,
+not proof that the learner used the control.
+If you directly ask Colleague to “Watch me while I do this,” it starts the same
+Learning poller shown by the eye button. The poller can report only named Vibe64
+navigation controls, declared exercise responses and saved lesson state—not SQL
+contents, arbitrary app-internal activity, screenshots or typed text. Ask how it
+works for an explanation without starting it. Pause, Resume and Stop act on the
+same watch ID; Stop does not stop Preview, Main or the lesson.
 Code, file, terminal and visual investigation belongs to a coding conversation;
 Colleague can ask that agent and relay its result, but cannot itself read source,
 execute a shell command or inspect the screen. A navigation request does not
 authorize editing source, stopping work or changing settings.
+
+
+In **Files → Project Backups (2w retention)**, use **Upload**, drag files into the
+folder, or choose **New folder**. Open a text file to edit it and choose **Save**;
+use its menu for **Rename** or **Delete**, and **Download** to keep a permanent
+copy. The same controls are available in Session Dropzone. On phones, file
+browsing and editing share the pane and secondary actions are in the file menu.
+Confirm **Delete** to remove the selected item; **New folder** creates an empty
+folder in the currently displayed directory.
+Uploads accept individual files up to 500 MiB; use a zip to exchange a directory.
+
+Project Backups is an ordinary directory outside Git. The coding agent can put
+files there using its supplied path; **Copy AI path** lets you refer to that same
+directory. Switching, renewing or archiving a session does not remove the
+project's backups. Every file displays an expiry date. Hosted daily maintenance
+deletes files after 14 days without a write or filesystem change; a newly copied
+file gets a fresh window even if it preserves an older modification date. Download
+anything you want to retain permanently. This folder does not automatically
+snapshot your project. Session Dropzone is temporary and disappears when its
+session is successfully archived.
+
+Colleague can explain these controls and open Files. Ask the coding agent to
+create or inspect backup files; Colleague itself has no filesystem or shell
+access. If a backup operation reports busy, wait for the current upload or
+maintenance to finish and retry. Symbolic links are not browsable or cleaned
+automatically. Workspace upgrade recovery copies remain private operator data
+and are not exposed in the project's backup folder.

package/docs/colleague-usage/database.md

@@ -69,6 +69,17 @@ Colleague can explain these views, inspect authorized status, refresh schema
 metadata, open a specific view or exact table, and request cancellation of the
 identified active query when asked. It acknowledges actual view/table selection;
 that is not proof a query succeeded. It does not receive rows or write SQL itself.
+In a practice lesson, **Dashboard → Database** (a session tool of the lesson's
+ordinary Dashboard) shows the practice app's ERD, tables and data. It is
+editable like any project's database: cell edits, **Add row**, row deletion,
+confirmed data-changing SQL, snippets and ERD arrangement work as described
+above and change only that lesson's practice database. The database
+**Copilot** is not available there; ask your lesson teacher instead. See
+[Choosing lessons and Learning conversations](learning-mode-ui.md).
+For an active supervised lesson, Colleague or its bound Main teacher can reveal
+the exact exercise session's **ERD** in **Workspace** while Learning stays on.
+The initiating browser must confirm the same project, session and attempt; this
+teacher demonstration never counts as the learner's own ERD task or a pass.
 Ask it to send database investigation or a requested change to a coding conversation
 and report the evidence. Data-changing work retains its existing confirmation
 requirements; a how-to question alone authorizes no query or mutation.