Consolidate module guides and unreleased purchasing documentation

README.md

@@ -70,3 +70,16 @@ text, screenshots and the catalog baseline together when reviewing another relea
 PRs run the website's canonical parser exported into `.github/validator/`, with its source revision and checksum in `source.json`. It includes only the parser and public Composer dependencies, so contributors need no access to the private website repo. Refresh it with `php artisan docs:export-validator ../docs/.github/validator` from website, then update its Composer lock when dependencies change. Validated pushes to `master` request an import by exact commit SHA and wait for publication. Failed imports preserve the previous revision. Embeddings are queued separately; ordinary docs and search continue during provider outages.
 
 Configure `CI_DOCS_TOKEN` as a GitHub Actions secret with the same dedicated value in the website deployment. The token authorizes docs imports only. Initial rollout requires the website implementation and worker before this workflow is enabled. Operations, rollback, AI budgets and the old-host cutover are documented in the website's `docs/operations.md`.
+
+## Canonical guide ownership
+
+Keep user-facing guides in this repository. The v3 book includes official-module
+usage under **Optional modules**; modules still need to be installed separately.
+The AI Assistant module guide is distinct from the core MCP connection guide.
+
+Features ahead of the published release belong in [`drafts/`](drafts/README.md).
+Drafts are stored for review but are outside the website importer and AI corpus.
+See [the consolidation inventory](verification/guide-consolidation-2026-09-28.md)
+for source locations and remaining publication work. Repository READMEs may keep
+short introductions and installation pointers. Architecture decisions, contributor
+instructions, and private deployment runbooks stay with the code they describe.

content-review.json

@@ -1293,7 +1293,8 @@
         "release": "3.0.0-alpha.10",
         "source_commit": "c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7",
         "review_sources": [
-          "release source and settled application screen"
+          "release source and settled application screen",
+          "Cross-links to the source-reviewed official module guides; existing release screenshots retained."
         ],
         "screenshots": [
           {
@@ -1308,7 +1309,8 @@
           }
         ],
         "status": "rewritten",
-        "legacy_anchors": []
+        "legacy_anchors": [],
+        "review_date": "2026-09-28"
       },
       "installation": {
         "title": "Installation",
@@ -1551,7 +1553,8 @@
         "review_sources": [
           "config/mcp.php",
           "app/Platform/Mcp",
-          "MCP settings screen"
+          "MCP settings screen",
+          "Cross-links to the source-reviewed official module guides; existing release screenshots retained."
         ],
         "screenshots": [
           {
@@ -1569,8 +1572,80 @@
         "legacy_anchors": [
           "requirements",
           "safety"
-        ]
+        ],
+        "review_date": "2026-09-28"
+      },
+      "guide/tasks-projects": {
+        "title": "Tasks and projects",
+        "release": "3.0.0-alpha.10",
+        "source_commit": "c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7",
+        "review_date": "2026-09-28",
+        "review_sources": [
+          "InvoiceShelf/InvoiceShelf@c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7: resources/scripts/extensions/runtime.ts, composer.lock",
+          "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: README.md",
+          "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: module.json",
+          "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: resources/js/registrations/projects.ts",
+          "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: resources/js/registrations/tasks.ts",
+          "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: resources/js/registrations/billing.ts",
+          "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: resources/js/registrations/reports.ts",
+          "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: app/Support/ModuleRegistration.php",
+          "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: app/Application/TimerService.php",
+          "InvoiceShelf/module-tasks-projects@94d3e51a2fe4b5c09a350aa8808d4631d6573068: app/Application/TimeEntryService.php"
+        ],
+        "module": {
+          "repository": "InvoiceShelf/module-tasks-projects",
+          "version": "0.2.1",
+          "source_commit": "94d3e51a2fe4b5c09a350aa8808d4631d6573068"
+        },
+        "screenshots": [],
+        "status": "source-reviewed",
+        "browser_review": "pending; no connected browser in this session",
+        "legacy_anchors": []
+      },
+      "guide/ai-assistant-module": {
+        "title": "AI Assistant module",
+        "release": "3.0.0-alpha.10",
+        "source_commit": "c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7",
+        "review_date": "2026-09-28",
+        "review_sources": [
+          "InvoiceShelf/InvoiceShelf@c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7: resources/scripts/extensions/runtime.ts, composer.lock",
+          "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: README.md",
+          "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: module.json",
+          "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: resources/js/init.ts",
+          "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: resources/js/pages/AiConfigurationPage.vue",
+          "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: app/Providers/AiAssistantServiceProvider.php",
+          "InvoiceShelf/module-ai-assistant@bed8f7a9c23354ca052121cabd9a87745b5e48ef: app/Application/AiToolRegistry.php"
+        ],
+        "module": {
+          "repository": "InvoiceShelf/module-ai-assistant",
+          "version": "1.0.0",
+          "source_commit": "bed8f7a9c23354ca052121cabd9a87745b5e48ef"
+        },
+        "screenshots": [],
+        "status": "source-reviewed",
+        "browser_review": "pending; no connected browser in this session",
+        "legacy_anchors": []
+      }
+    }
+  },
+  "consolidation": {
+    "date": "2026-09-28",
+    "scope": "User-facing guides; engineering specifications and operational runbooks remain with their owning repositories.",
+    "unreleased": [
+      {
+        "path": "drafts/v3/guide/purchasing.md",
+        "source_repository": "InvoiceShelf/InvoiceShelf",
+        "source_commit": "9fba5b7a6753f95a2cedd1d92947c7570aeff184",
+        "pull_request": 903,
+        "published": false
       }
+    ],
+    "version_exclusions": {
+      "2": [
+        "guide/tasks-projects",
+        "guide/ai-assistant-module",
+        "guide/purchasing"
+      ]
     }
   }
 }

docs.json

@@ -234,6 +234,19 @@
             }
           ]
         },
+        {
+          "title": "Optional modules",
+          "items": [
+            {
+              "title": "Tasks and projects",
+              "slug": "guide/tasks-projects"
+            },
+            {
+              "title": "AI Assistant",
+              "slug": "guide/ai-assistant-module"
+            }
+          ]
+        },
         {
           "title": "Company & account",
           "items": [

docs/v3/guide/ai-assistant-module.md

@@ -0,0 +1,80 @@
+---
+versions: ['3']
+reviewed_against: c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7
+reviewed_hash: b11535291ef5c593e374da5bfbab4cc7feff767decd4f9356e5a5a37175c1a08
+---
+
+# AI Assistant module
+
+**AI Assistant** is an optional official module for InvoiceShelf 3. This guide
+covers module **1.0.0** with the v3 host described by this book. It adds a chat drawer
+and writing assistance inside InvoiceShelf.
+
+This is separate from [external assistants connected through MCP](./ai-assistants.md)
+and from **Ask AI** on the documentation website. The module's business-data tools
+are read-only; an MCP connection may have separately approved write access, while
+documentation answers do not access company records.
+
+## Install and connect a provider
+
+1. A super administrator installs and enables **AI Assistant** in
+   **Administration → Modules**. See [Modules](./modules.md).
+2. Open **Administration → Settings → AI Assistant**.
+3. Enable **AI Assistant**, select **OpenRouter**, and enter the provider API key.
+4. Enable the capabilities you want to offer and select a model for each one.
+5. Select **Save settings**, then **Test connection**. The test control is shown
+   when AI Assistant is enabled.
+
+Your administrator supplies and funds the OpenRouter account. The module does not
+include provider credit or a shared API key. Keep keys out of screenshots,
+documents, and support messages.
+
+## Choose capabilities
+
+- **Assistant chat** makes the conversational drawer available on company pages.
+  Use the AI header action to open it. Start a new conversation when changing topics.
+- **Editor text generation** adds writing tools to supported rich-text editors.
+  Review suggested text before using it in a document or email.
+
+The capabilities can be enabled independently. If a control is missing, check the
+module state, provider configuration, enabled capabilities, and your company access.
+
+## Company-specific configuration
+
+The administrator's configuration is the default. A company owner can open
+**Company Settings → AI Assistant**, enable **Use a company-specific AI configuration**,
+and choose a different provider configuration or models for that company.
+
+Leaving that setting off uses the global configuration. Replacing a key updates the
+stored key; leaving its masked value unchanged retains it.
+
+## Data and permissions
+
+Prompts and any business data requested through the module's read-only tools are
+sent to OpenRouter and the selected model provider. Enable the module only with
+provider and model choices appropriate for your business data.
+
+Tools operate in the active company and respect the signed-in user's InvoiceShelf
+permissions. The module cannot create or change invoices, expenses, customers,
+payments, or other business records. Verify amounts and document details in the
+application before acting on an answer.
+
+API keys are encrypted at rest and masked in settings. An assistant response is not
+a reason to share an administrator password or increase another user's permissions.
+
+## Troubleshooting
+
+If the connection test fails, check the provider key, available provider credit,
+selected model, and provider URL. After changing settings, save and test again.
+
+If chat cannot access a record, check the active company and your normal permission
+to view that record. If only writing tools are missing, confirm **Editor text
+generation** is enabled separately from chat.
+
+## Disable or remove the module
+
+Disabling hides the module's controls and routes but retains its configuration and
+conversations. Uninstalling removes the package. Selecting **Remove module data**
+also removes stored module settings and conversations; this is permanent.
+
+See [Backups](./backups.md) before removing stored data.

docs/v3/guide/ai-assistants.md

@@ -1,15 +1,15 @@
 ---
 versions: ['3']
 reviewed_against: c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7
-reviewed_hash: d3680360e46bb80cce274cb499f2a51afc4f121ac10c6791b49ef995c6732cc5
+reviewed_hash: 0f7761676adeac9a316a343d179f234fadc6615f6b016a17704b96fe97eba9dc
 anchor_aliases:
   requirements: redirect-domains
   safety: ai-assistants-mcp
 ---
 
 # AI assistants (MCP)
 
-InvoiceShelf 3 includes an MCP server so a compatible assistant can work with your company’s data through authorized application tools. This is separate from **Ask AI in these docs**, which answers documentation questions and does not access your invoices.
+InvoiceShelf 3 includes an MCP server so a compatible assistant can work with your company’s data through authorized application tools. This is separate from the optional [AI Assistant module](./ai-assistant-module.md) inside InvoiceShelf and from **Ask AI in these docs**, which answers documentation questions and does not access your invoices.
 
 ## Switching it on
 

docs/v3/guide/modules.md

@@ -1,7 +1,7 @@
 ---
 versions: ['3']
 reviewed_against: c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7
-reviewed_hash: d72256251aa028f63c168ed41341fe1c538dbe5034a26ba939c34e45e53cdf01
+reviewed_hash: a147389d5088bb1bd1b5db2949100769d8b9f45badb4833108648abad96cdb05
 ---
 
 # Modules
@@ -23,3 +23,16 @@ Installation and activation are administrator tasks. Within a company, **Setting
 ![InvoiceShelf 3 company module settings](/images/v3/modules.webp)
 
 If access changes on the website, reconnect or refresh the installation as the interface instructs. Do not share marketplace tokens or approval codes in screenshots or support messages.
+
+## Official module guides
+
+Optional module workflows have their own guides:
+
+- [Tasks and projects](./tasks-projects.md): projects, task views, timers,
+  timesheets, and preparing invoices from tracked work.
+- [AI Assistant](./ai-assistant-module.md): provider configuration, chat, writing
+  tools, and access to company data.
+
+Install a compatible package first. A module guide does not mean that module is
+bundled or enabled in your installation. For connecting an external assistant,
+use [AI assistants (MCP)](./ai-assistants.md).

docs/v3/guide/tasks-projects.md

@@ -0,0 +1,86 @@
+---
+versions: ['3']
+reviewed_against: c4f6f8af2163fcc3a0c97d2046fcf22c1d47d0e7
+reviewed_hash: a4eb7814a2da8658ac9de56406720cbe6c52b127e9c22c3861c3a7a8091a184c
+---
+
+# Tasks and projects
+
+**Tasks and Projects** is an optional official module for InvoiceShelf 3. This guide
+covers module **0.2.1** with the v3 host described by this book. Install a compatible
+module package before looking for these screens; they are not enabled by default.
+
+## Install and configure
+
+A super administrator installs and enables **Tasks and Projects** through
+**Administration → Modules**. See [Modules](./modules.md) for marketplace pairing
+and package compatibility.
+
+Open **Company Settings → Tasks and Projects** to set the default hourly rate,
+time-rounding rules, first day of the week, and whether members may see each
+other's time. Settings also control starting a timer when a task is created,
+locking invoiced tasks, hiding invoiced tasks from the board, and which task/time
+information appears on invoice lines.
+
+The module adds **Projects** and **Tasks** to the menu. If either is missing, check
+that the module is enabled and that your company role permits viewing it.
+
+## Organize work in projects
+
+Create a project with a name, optional customer, status, and description. Set a
+billable rate, budget, and due date when needed. A project without a customer is
+internal work and is not available for customer invoicing.
+
+Use a project's tabs to review its overview, tasks, time, and members. Members can
+have project-specific hourly rates. Check the customer and currency before
+starting work that will be billed.
+
+## Choose a task view
+
+Open **Tasks** and use the view selector:
+
+- **List** shows sortable task rows.
+- **Board** groups tasks by the company's task statuses and supports drag ordering.
+- **Week** shows the timesheet for the selected week.
+
+Project, member, and status filters stay in the URL when switching views. Open a
+task to see its details and time log.
+
+## Track time
+
+Start or stop a timer from a task row, board card, task page, or the floating timer
+control. The header shows the elapsed time and links to the running task. Only one
+timer can run per user in each company; starting another offers to stop the first.
+
+You can also enter time manually. Review its start, end, duration, description,
+billable flag, and member. Rounding follows the company's module settings.
+
+Rates are resolved from the task, then the member's project rate, the project
+rate, and finally the company default. The rate is saved with the time entry so a
+later rate change does not rewrite past work.
+
+## Turn work into an invoice
+
+Select **Invoice** from a task, a selection of tasks, or a project to prepare a
+**draft invoice**. The draft opens in InvoiceShelf's invoice editor with one line
+per task. Review the dates, descriptions, tax, and totals before sending it.
+
+A selection spanning different customers or currencies is refused. Use separate
+invoices for those groups.
+
+The **Unbilled time** page, linked from Reports and the Projects header, brings
+uninvoiced time together across projects. Use it to review what is ready to bill
+and leave individual entries out when necessary.
+
+Once an entry is on an invoice, its time, billable flag, and task cannot be changed.
+Its description remains editable. Your role needs the module's invoicing permission
+and InvoiceShelf's create/edit-invoice permissions to use this workflow.
+
+## Disable or remove the module
+
+Disabling the module hides its screens and routes while retaining data.
+Uninstalling removes the package. Selecting **Remove module data** also removes
+the module's settings and stored project/task/time records; this is permanent.
+
+Back up the installation before removal and review invoices already created from
+tracked work. See [Backups](./backups.md).

drafts/README.md

@@ -0,0 +1,15 @@
+# Unreleased documentation
+
+This directory holds user guides for features that are not included in the
+published books' pinned releases. The website importer reads only `docs/`, so
+these drafts do not enter published navigation, keyword search, or AI answers.
+
+| Draft | Application work | Publication condition |
+|---|---|---|
+| [Bills and supplier payments](./v3/guide/purchasing.md) | [InvoiceShelf PR #903](https://github.com/InvoiceShelf/InvoiceShelf/pull/903) | Review against the release that includes purchasing. |
+
+To publish a draft, verify the final implementation and UI against the target
+release, move it into the appropriate versioned book, add navigation, and record
+its real source review and hash. Update the book's baseline and screenshots when
+advancing the release. Never label unreleased behavior as available in the current
+book merely to pass validation.