<?php
function enrepManualMeta(): array
{
    return [
        'title' => 'EnRep User Manual',
        'subtitle' => 'Practical guidance for day-to-day users',
        'version' => '1.0',
        'last_reviewed' => '10-07-2026',
        'owner' => 'EnRep Administration',
    ];
}

function enrepManualSections(): array
{
    return [
        [
            'id' => 'getting-started',
            'title' => 'Getting Started',
            'summary' => 'EnRep brings client records, assets, inspections, reports, delivery, and written schemes into one working system.',
            'figure' => [
                'src' => 'includes/manual/images/enrep-workflow.svg',
                'alt' => 'EnRep workflow showing clients, assets, inspections, reports, delivery, and written schemes',
                'caption' => 'Most EnRep tasks follow the same route: start with the client, find the asset, complete the work, then issue or update the related record.',
            ],
            'body' => [
                'Most work in EnRep starts with a client. From the client record you can open the asset schedule, view sites, add new equipment, continue reports, and manage delivery. The options shown to you depend on your role, so an administrator may see wider management tools while a surveyor may see the work assigned to them.',
                'The top bar shows your current location in the system and gives access to notifications, support tickets, and your user menu. The side menu is used for moving between the main parts of EnRep. When you are unsure where you are, use the breadcrumb trail at the top of the screen to step back to the client or previous area.',
            ],
            'features' => [
                [
                    'title' => 'Navigation and breadcrumbs',
                    'text' => 'Breadcrumbs are there to stop you losing your place. If you have opened an asset, report, written scheme, or delivery page from a client, use the breadcrumb trail to move back through that same path instead of starting another search.',
                ],
                [
                    'title' => 'Role-based options',
                    'text' => 'EnRep shows different tools depending on your role. This keeps daily screens focused: surveyors can work on assigned inspections, while administrators can see wider client, reporting, and management tools.',
                ],
            ],
            'items' => [
                'Log in with your assigned account.',
                'Use the side menu for main navigation.',
                'Use breadcrumbs to return to client, schedule, or list pages.',
                'Use the user menu to open your profile or log out.',
            ],
            'best_practice' => [
                'Keep one browser tab per main task where possible.',
                'Refresh the page if a list appears out of date after saving.',
            ],
        ],
        [
            'id' => 'clients-sites',
            'title' => 'Clients and Sites',
            'summary' => 'A client record holds the customer details. Sites hold the physical locations where assets are registered.',
            'body' => [
                'Client and site information should be kept accurate because it appears throughout the system. Site names, addresses, postcodes, renewal dates, and contact information all support later work such as scheduling, reporting, and delivery.',
                'A client may have one site or many. Each asset belongs to a site, so it is normally best to create the correct location before adding assets. Location notes should be used for information that applies to the site as a whole, such as access instructions or safety notes.',
            ],
            'features' => [
                [
                    'title' => 'Client record',
                    'text' => 'The client record is the administrative home for the customer. It should hold the details that apply to the customer as a whole, such as the main name, contract information, and general contact details.',
                ],
                [
                    'title' => 'Site record',
                    'text' => 'Sites describe where the work physically happens. Accurate site names and addresses make schedules, reports, and delivery packs easier to understand, especially for clients with several locations.',
                ],
                [
                    'title' => 'Location notes',
                    'text' => 'Use location notes for information that applies to visiting or working at the site, such as access instructions, induction requirements, or recurring site safety information.',
                ],
            ],
            'items' => [
                'Find the client from the client list or dashboard search.',
                'Open the client schedule to view active assets.',
                'Create a location before registering assets for that site.',
                'Keep contact and renewal information up to date.',
            ],
            'best_practice' => [
                'Use site names people will recognise, such as Main Workshop or Boiler House.',
                'Put access notes in the location record instead of repeating them on every asset.',
            ],
        ],
        [
            'id' => 'asset-schedule',
            'title' => 'Asset Schedule',
            'summary' => 'The asset schedule is the working list of equipment for a client.',
            'figure' => [
                'src' => 'includes/manual/images/asset-schedule.svg',
                'alt' => 'Asset schedule search, filters, asset actions, and active asset table',
                'caption' => 'The schedule combines finding tools, status filters, asset actions, and the live equipment list for the selected client.',
            ],
            'body' => [
                'The schedule is used to find equipment, check due dates, review previous results, and start asset-related work. It can be searched by common identifying information such as description, plant number, serial number, manufacturer, model, location, sub-location, report result, or due date.',
                'The buttons above the schedule change depending on whether any rows are selected. With no selection, the toolbar is for client-level tasks such as adding assets, importing assets, creating locations, opening delivery, viewing incomplete reports, and switching between active and archived items. Once one or more assets are selected, the toolbar changes to bulk actions for the selected items.',
                'Each row also has its own Actions buttons. Use these when the task applies to one asset only, such as starting a report, viewing completed reports, moving the item, cloning it, archiving it, opening notes, or editing the asset record.',
                'The schedule is also the place where active and archived items are separated. Active assets are items currently in service or still managed for the client. Archived items should be reserved for equipment that is no longer active but still needs to remain on record.',
            ],
            'features' => [
                [
                    'title' => 'Search',
                    'text' => 'Use search when you already know part of the asset identity. It is intended for quick narrowing, so a partial serial number such as RS214 should still help you find a full serial number such as RS2149. It can also be used for plant numbers, descriptions, models, locations, due dates, and previous report results.',
                ],
                [
                    'title' => 'Overdue, Pending, and Not Due',
                    'text' => 'These filters are for planning inspection work. Overdue shows assets already past their due date, Pending shows assets approaching attention soon, and Not Due removes immediate work so you can review the wider schedule without urgent items dominating the view.',
                ],
                [
                    'title' => 'New Asset',
                    'text' => 'New Asset is for registering a single item when you have the details in front of you. It is the best route for one-off additions, replacements, or items discovered during a visit because you can choose the correct client, site, description, identification numbers, frequency, and notes directly.',
                ],
                [
                    'title' => 'Import Asset',
                    'text' => 'Import Asset is for creating many assets from a prepared CSV file, usually when taking on a new client, adding a large site, or transferring a cleaned asset list into EnRep. It saves repeated data entry, but it should only be used when the spreadsheet has been checked because every committed row becomes part of the live schedule.',
                ],
                [
                    'title' => 'Archived Items',
                    'text' => 'Archiving removes an item from normal active scheduling without deleting its history. Use it when equipment has been removed, replaced, scrapped, or is no longer part of the managed scope, while keeping reports and previous information available for reference.',
                ],
                [
                    'title' => 'Select Visible and Deselect Visible',
                    'text' => 'These controls select or clear the rows currently shown on the page. They are useful after searching or filtering because they let you build a bulk selection from the visible results rather than ticking each item one at a time.',
                ],
                [
                    'title' => 'Selection toolbar',
                    'text' => 'When at least one row is selected, EnRep replaces the normal top actions with bulk tools. Item Move transfers selected assets to another site, Item Archive archives the selected assets, Chain Items groups related assets together, Edit Chain changes an existing chain relationship, Code Change updates the plant/report code for the selected assets, and PNA Items applies a PNA workflow to the selected group.',
                ],
                [
                    'title' => 'Row actions',
                    'text' => 'The row action buttons are for one asset at a time. New Report starts an inspection for that asset, Completed Reports opens its report history, Move transfers it to another site, Clone Item creates a similar asset record, Archive or Reinstate changes whether it is active, and Edit opens the asset details. Extra note or chain buttons appear only when that item has location notes, item notes, or a chain relationship.',
                ],
            ],
            'items' => [
                'Search using the most reliable identifier first, such as serial number or plant number.',
                'Use status filters before planning visits or chasing overdue work.',
                'Use the normal top toolbar for client-level schedule tasks.',
                'Tick rows when you need the bulk selection toolbar.',
                'Use the row Actions buttons when the task applies to one asset only.',
                'Choose New Asset for one item and Import Asset for a checked batch of rows.',
                'Archive assets only when they should no longer appear as active managed equipment.',
            ],
            'best_practice' => [
                'Record plant and serial numbers exactly as shown on the item.',
                'Keep descriptions consistent so assets remain easy to search.',
                'Use sub-locations for practical finding details, not full addresses.',
            ],
        ],
        [
            'id' => 'asset-import',
            'title' => 'Importing Assets',
            'summary' => 'CSV import is intended for adding multiple assets to a client schedule efficiently.',
            'body' => [
                'The import process expects a specific template. The column headings should not be renamed or rearranged. Before committing an import, EnRep reviews the rows and reports validation issues such as missing descriptions, missing plant or serial numbers, date problems, or possible duplicates.',
                'Import is most useful when the source data has already been cleaned. If the spreadsheet contains inconsistent descriptions, mixed date formats, or unknown locations, it is better to correct those before committing the import.',
            ],
            'features' => [
                [
                    'title' => 'Template',
                    'text' => 'The template protects the import process by giving EnRep the column names it expects. Keeping the headings unchanged allows the system to read descriptions, safe working loads, plant numbers, serial numbers, manufacturers, dates, frequencies, and sub-locations consistently.',
                ],
                [
                    'title' => 'Review before commit',
                    'text' => 'Uploading a CSV should be treated as a review stage, not the final step. Use the validation messages to correct missing details, date issues, or possible duplicates before committing the rows to the live schedule.',
                ],
                [
                    'title' => 'Duplicates',
                    'text' => 'Duplicate checks help avoid creating two active records for the same physical item. If the source list contains both a plant number and serial number, check both carefully before import because those values are often what users search for later.',
                ],
            ],
            'items' => [
                'Download the current template.',
                'Complete the rows without changing the headings.',
                'Save the CSV as UTF-8.',
                'Upload and review validation messages.',
                'Commit the import only once the rows are correct.',
            ],
            'best_practice' => [
                'Use manageable batches if the source data has not been checked.',
                'Use existing descriptions where possible so frequencies and plant codes remain consistent.',
            ],
        ],
        [
            'id' => 'reports',
            'title' => 'Reports and Inspections',
            'summary' => 'Reports are created from an asset and completed through the relevant inspection form.',
            'figure' => [
                'src' => 'includes/manual/images/report-workflow.svg',
                'alt' => 'Report workflow from asset selection through inspection, incomplete reports, completion, and delivery',
                'caption' => 'Reports move from asset selection into an inspection form. Drafts remain available as incomplete reports until they are completed or removed.',
            ],
            'body' => [
                'Inspection forms capture the condition, result, observations, defects, and supporting information for an asset. Required fields must be completed before the report can be treated as complete. Some forms also use visual status indicators to show whether the inspection is passing, has warnings, or has defects.',
                'Good report text should be clear enough for another person to understand what was inspected and what action, if any, is required. Avoid vague wording. A report should be factual, readable, and suitable for issuing to a client.',
            ],
            'features' => [
                [
                    'title' => 'Starting a report',
                    'text' => 'Start from the correct asset so the report inherits the right client, site, asset identifiers, and inspection context. If an asset record is wrong, correct the asset first where possible rather than compensating in the report text.',
                ],
                [
                    'title' => 'Saving during an inspection',
                    'text' => 'Saving protects work in progress and creates a route back through Incomplete Reports if the inspection cannot be finished immediately. This is especially useful for longer forms or when information needs checking before finalising.',
                ],
                [
                    'title' => 'Results and defects',
                    'text' => 'The result should reflect the inspection outcome, while observations and defects should explain the evidence behind it. A useful defect tells the reader what was found, where it was found, and what should happen next.',
                ],
            ],
            'items' => [
                'Open the asset and choose the correct report or inspection action.',
                'Complete the required fields.',
                'Save regularly during longer inspections.',
                'Use incomplete reports to resume work that was started but not finished.',
            ],
            'best_practice' => [
                'Write observations and defects in plain language.',
                'Avoid abbreviations unless they are standard for the report type.',
                'A useful defect explains what was found, where it was found, and what action is needed.',
            ],
        ],
        [
            'id' => 'incomplete-reports',
            'title' => 'Incomplete Reports',
            'summary' => 'Incomplete reports are inspections that have been started but not fully completed.',
            'body' => [
                'Incomplete reports help prevent work from being lost. They are also a useful reminder that a report may already exist for an asset. Administrators can review incomplete work across surveyors, while surveyors see the incomplete reports that belong to them.',
                'An incomplete report should normally be continued and completed. It should only be removed when it was created in error, such as a duplicate report or a report started against the wrong asset.',
            ],
            'features' => [
                [
                    'title' => 'Continuing a draft',
                    'text' => 'Use the incomplete report entry to return to the report that was already started. This prevents duplicate inspections and keeps the original saved answers, observations, and attachments together.',
                ],
                [
                    'title' => 'Surveyor view',
                    'text' => 'Surveyors should normally see only the outstanding reports assigned to them. This keeps the list focused on work they can complete themselves.',
                ],
                [
                    'title' => 'Administrator view',
                    'text' => 'Administrators can use the wider view to spot old drafts, support surveyors, and keep incomplete work from building up across the business.',
                ],
            ],
            'items' => [
                'Open Incomplete Reports from the relevant page.',
                'Use Edit Report to continue the inspection.',
                'Delete only reports that were created in error.',
            ],
            'best_practice' => [
                'Check incomplete reports before starting a new inspection for the same asset.',
                'Keep incomplete reports low by finishing drafts promptly.',
            ],
        ],
        [
            'id' => 'delivery',
            'title' => 'Report Delivery',
            'summary' => 'Delivery records or sends completed report documents for a client.',
            'body' => [
                'Once reports are complete, they can be delivered to the client or marked as sent. Delivery may be done individually or in batches depending on the client and the reports ready at the time. Before sending, check that the correct reports and recipients have been selected.',
                'The delivery record is important because it shows what has been issued. Do not mark reports as delivered simply to clear a list; only do so when the documents have genuinely been issued or otherwise recorded as delivered.',
            ],
            'features' => [
                [
                    'title' => 'Outstanding reports',
                    'text' => 'Outstanding reports are completed documents that still need issuing or recording as delivered. Reviewing this list helps make sure clients receive the right paperwork and that completed inspections do not sit unnoticed.',
                ],
                [
                    'title' => 'Recipients and message text',
                    'text' => 'Before sending, check the recipient list and message text in the same way you would check an email before pressing send. Delivery is client-facing, so the correct contact and clear wording matter.',
                ],
                [
                    'title' => 'Batch delivery',
                    'text' => 'Batch delivery is useful when several reports are ready for the same client. It reduces repeated sending work, but it also increases the need to check that every selected report belongs in the same issue.',
                ],
            ],
            'items' => [
                'Open Deliver Reports from the client schedule when available.',
                'Review outstanding reports before delivery.',
                'Check recipients and message text.',
                'Use batch delivery when several reports are ready for the same client.',
            ],
            'best_practice' => [
                'Use clear email subjects and concise message text.',
                'Confirm the attachments or report list before sending.',
            ],
        ],
        [
            'id' => 'written-schemes',
            'title' => 'Written Schemes',
            'summary' => 'Written Schemes are used for PSSR and related system documentation.',
            'figure' => [
                'src' => 'includes/manual/images/written-scheme.svg',
                'alt' => 'Written scheme with parts, system type, revisions, and delivery',
                'caption' => 'A written scheme links the scheme record to the assets covered by that system, plus its revisions and issued documents.',
            ],
            'body' => [
                'Written Schemes group relevant assets into a documented system. A PSSR asset can be attached to an existing scheme or used to create a new one. Once attached, the PSSR data area shows the current written scheme so users can see the relationship when editing the asset.',
                'The Parts tab controls which assets are covered by the written scheme. Revisions should be used to record meaningful changes to the scheme. Where revisioning is paused, the scheme number should not increase and part changes should not create revision history entries.',
            ],
            'features' => [
                [
                    'title' => 'System Type',
                    'text' => 'System Type identifies the kind of pressure system the PSSR asset belongs to. Keeping it populated helps distinguish relevant PSSR items from ordinary assets and supports the written scheme parts workflow.',
                ],
                [
                    'title' => 'Parts',
                    'text' => 'Parts are the assets covered by the written scheme. Add an asset only when it genuinely belongs to the system described by the scheme, and remove it when it is no longer part of that system.',
                ],
                [
                    'title' => 'Revisions',
                    'text' => 'Revisions should describe meaningful changes to the scheme, such as adding or removing covered equipment, updating documentation, or changing the system record. If revisioning is paused, part changes should not create revision history entries.',
                ],
                [
                    'title' => 'Delivery',
                    'text' => 'Delivery is used once the written scheme documents are ready to issue. As with report delivery, check that the generated document or pack matches the scheme before sending it to the client.',
                ],
            ],
            'items' => [
                'Attach a PSSR asset to an existing scheme or create a new scheme.',
                'Use Parts to add or remove covered assets.',
                'Use Revisions to record meaningful changes.',
                'Use delivery options when written scheme documents are ready to issue.',
            ],
            'best_practice' => [
                'Keep System Type populated on PSSR assets.',
                'Only attach assets that genuinely belong to the system covered by the scheme.',
            ],
        ],
        [
            'id' => 'text-guidance',
            'title' => 'Text and Naming Best Practice',
            'summary' => 'Consistent text makes EnRep easier to search, review, and report from.',
            'body' => [
                'Clear text helps everyone who uses the record later. Asset descriptions, site names, notes, defects, and email messages should be written for the next person who needs to understand them. Avoid relying on memory, shorthand, or local nicknames unless they are already standard for the client.',
                'Formal report text should be factual and professional. Notes can provide context, but the final report wording should still be suitable for a client to read.',
            ],
            'items' => [
                'Use sentence case for notes and descriptions.',
                'Keep item descriptions short and recognisable.',
                'Avoid unexplained shorthand.',
                'Check spelling before delivery.',
            ],
            'best_practice' => [
                'Good asset text: Air Receiver - Tank 2.',
                'Less useful asset text: TANK!!!! or Misc item.',
                'Good defect text: Pressure gauge face damaged; replace gauge before next use.',
            ],
        ],
        [
            'id' => 'getting-help',
            'title' => 'Getting Help',
            'summary' => 'Use support routes when a workflow is unclear or a page does not behave as expected.',
            'body' => [
                'When asking for help, include enough detail for someone else to reproduce or understand the problem. The most useful reports include the client name, asset, report number if known, page name, and the action you were trying to complete.',
                'If the issue is about searching or filtering, include the exact search term used and what result you expected. If the issue is visual, a screenshot is often the quickest way to explain it.',
            ],
            'items' => [
                'Use the support ticket option where available.',
                'Include the client, asset, report number, and page name where relevant.',
                'Include exact search terms or button names when reporting a search or workflow issue.',
            ],
            'best_practice' => [
                'Do not repeatedly press save if the page appears stuck.',
                'Take a screenshot when an unexpected message or result appears.',
            ],
        ],
    ];
}

function enrepManualCoverageRegister(): array
{
    return [
        ['area' => 'Clients and Sites', 'covered' => 'Client search, site records, renewal and location guidance', 'update_trigger' => 'Client details, site, or renewal workflow changes'],
        ['area' => 'Asset Schedule', 'covered' => 'Searching, filters, new assets, archive, import shortcut', 'update_trigger' => 'Schedule layout, search fields, filters, or toolbar changes'],
        ['area' => 'Asset Import', 'covered' => 'Template, UTF-8 CSV, required fields, duplicate review', 'update_trigger' => 'CSV template, validation, or import review changes'],
        ['area' => 'Reports and Inspections', 'covered' => 'Starting, saving, incomplete reports, report text quality', 'update_trigger' => 'Form workflow, result rules, or inspection status changes'],
        ['area' => 'Delivery', 'covered' => 'Outstanding reports, delivery, email checks', 'update_trigger' => 'Delivery, batch issue, or email recipient changes'],
        ['area' => 'Written Schemes', 'covered' => 'PSSR attachment, parts, revision guidance', 'update_trigger' => 'PSSR, LOLER, written scheme, or revision behaviour changes'],
        ['area' => 'Text Guidance', 'covered' => 'Naming, notes, defects, email wording', 'update_trigger' => 'Terminology, client-facing wording, or report text standard changes'],
    ];
}

function enrepManualUpdateChecklist(): array
{
    return [
        'When a user-facing feature is added, changed, hidden, or renamed, check whether one of the manual sections needs updating.',
        'When a button label or page name changes, update the matching manual steps.',
        'When a workflow gains a new validation rule, warning, or required field, add it to the relevant section.',
        'When support receives repeated questions about the same workflow, add a short good-practice note.',
        'After updating the manual content, open the manual page and download the PDF to confirm both versions still read correctly.',
    ];
}
