Next (0.1 RC1 Preview)

Version and review

These editable Next guides describe Pūnaha 0.1 RC1, embedded as 0.1.0-rc.1. Source review uses Product commit 25748655d6befa9eb11356075f2ca5f909edc4b3 with local Help changes reviewed on 6 October 2026. A signed RC1 package has not yet been matched to this documentation.

These guides are publicly available. RC1 packages are available for evaluation and acceptance testing. The first production release is still pending. RC1 is not a production support commitment.

Download the RC1 package

Open the RC1 package downloads on GitHub. This link selects the v0.1.0-rc.1-terms-v2 release, which uses revised licence documents. The application version remains 0.1.0-rc.1.

In Assets, choose the complete Windows x64, Ubuntu amd64, Debian 13 amd64, or RHEL 9 x86_64 archive and SHA256SUMS.txt. Keep the extracted platform folder together and follow its INSTALL.md and verification instructions. GitHub's Source code archives contain repository documents, not the Product installer.

RC1 registration availability

Registration cannot be completed in RC1. Registration is planned for the first production version. The registration, renewal, and offline registration guides remain available so you can learn the process. Their activation steps cannot currently be completed for RC1.

Export your data before the 720 TPM powered on hour allowance ends. The allowance begins after first setup. Normal processing, administration, customer data access, and exports stop at the cutoff. Data is retained, but RC1 has no registration facility to restore normal use. This is not 30 calendar days. Time with the TPM powered off does not count. Stopping only the Product service does not pause the TPM clock.

Downloading or installing RC1 does not start a 12 month registered term. That term starts only on the issue date stated in a signed activation.

What the review establishes

Guidance follows the current Product source, its regression tests, and the supplied product policy. Source review does not prove every installed operating system, database, model, or cluster combination.

The API snapshot is generated for RC1 from that source. The generic development version in the Product checkout is not the RC1 package label.

Check the package you received

Use only the separate platform folder supplied for your target. Check its manifest, public verification certificate, executable version, and installation instructions. Never include private signing keys in a package.

Windows, Ubuntu, Debian, and RHEL package work does not establish equal lifecycle qualification on every host. Verify installation, restart, upgrade, recovery, and removal evidence for the exact package.

Known boundaries

• Changing an existing installation between database providers is not supported.
• GPU execution, full document completion, and cluster recovery need acceptance on the intended hardware.
• The offline registration workflow needs a configured Support portal and signing service on a separate connected device. Registration is unavailable in RC1.
• Existing screenshots are labelled as earlier development images. They are not RC1 screen captures.
• No full BPMN, DMN, or CMMN certification is claimed.

Next step

Read Install and run Pūnaha and Register and renew an installation.

About Pūnaha

Pūnaha is one full proprietary Product for personal and organisational use. It runs on infrastructure you control and combines knowledge, AI, workflows, and cases.

Start with your task

• Install and run Pūnaha, then finish first setup.
• Register or renew the installation.
• Find your way around for daily work.
• Add nodes and prepare shared storage.
• Install a solution package.
• Choose your starting point.

About this version

These are public Next guides for 0.1 RC1, embedded as 0.1.0-rc.1. RC1 packages are available for evaluation. The first production release is still pending. These guides can change. Read the RC1 downloads, registration availability, and limitations.

Registration is required

Future renewal pricing is undecided and may include a charge based on user group demand and actual maintenance and development costs. Proposed terms and prices will be disclosed in advance. Paid renewal requires explicit acceptance. There is no automatic charge or obligation to renew. Issued terms and prior accepted commitments are honoured. Optional support is separate.

Renew or export before the 720 powered on hour cutoff. Ordinary processing, administration, customer data access, and exports stop after that cutoff. Data is retained. This allowance is not 30 calendar days.

The current issued 12 month software licence term costs US$0 from the signed issue date. Register every independent installation. Approved cluster nodes belong to their installation. Optional paid support is separate.

Initial registration and renewal after term expiry each have 720 powered on hours of normal use. Powered off time does not count.

What the guides establish

Guidance follows reviewed Product source and tests. It does not certify every installed platform or full BPMN, DMN, or CMMN support.

Choose the description that matches your work

You may have more than one role. Start with the path that matches your current task.

System Owner

Use this path when you are responsible for the whole Pūnaha installation.

1. Understand Product versions and support.
2. Install and run Pūnaha.
3. Finish the first setup.
4. Create and manage tenants.
5. Set up access.

Tenant administrator

Use this path when you manage people, access, and settings for one tenant.

1. Find your way around Pūnaha.
2. Manage people and groups.
3. Manage access.
4. Manage Connections.
5. Manage tenant settings.

Solution builder

Use this path when you design workflows or case types.

1. Build a workflow.
2. Choose workflow steps.
3. Check, publish, and run the workflow.
4. Add safety checks and approvals.
5. Build a case type.

Case worker

Use this path when you complete work in an existing case.

1. Sign in and accept an invitation.
2. Check the tenant and find the right area.
3. Find and work with a case.
4. Change your personal settings.

Platform operator

Use this path when you run the services, storage, backups, and logs.

1. Install and run Pūnaha.
2. Choose how to run the services.
3. Check service health.
4. Use the Operations pages.
5. Plan storage and backups.
6. Use logs and audit records.

Integration developer

Use this path when you connect another system to Pūnaha. The API pages describe the current product contract and may change while the API is being improved.

1. Read the API overview.
2. Learn how API sign in works.
3. Learn how access works.
4. Check services and ports.

If you are still not sure

Start with Find your way around Pūnaha. You can also search for the task you want to complete.

RC1 installation ownership

System Owners should also read registration and renewal, node management, and database setup.

Choose the result you need

Each journey starts with what must be ready. It then takes you through the actions, the expected result, and common problems.

Set up the platform

1. Install and start Pūnaha.
2. Finish the first setup.
3. Create a tenant.
4. Invite a person and give access.

Prepare and use AI

1. Prepare a model and knowledge database.
2. Upload and search knowledge.

Build a solution

1. Build, publish, and run a workflow.
2. Build a case type and work with a case.
3. Configure and test a Connection.

Find an operational problem

Check operations, logs, and audit records when work is waiting, failed, or giving an unexpected result.

Additional RC1 journeys

• Register or renew an installation.
• Add approved nodes.
• Stop, assign, and resume documents.
• Install and activate a solution package.

One full Product

Pūnaha is one full proprietary product, not a trial. Personal and organisational use are permitted. You may use multiple versions and independent installations under their issued terms.

Separate versions still need compatible program files, databases, and configuration. Permission to use multiple versions does not mean that different versions can safely share them.

Product versions

The current package is 0.1 RC1, embedded as 0.1.0-rc.1. It is available for evaluation and acceptance testing. Read the RC1 downloads, registration availability, and limitations before installing.

Registration and licence

Future renewal pricing is undecided and may include a charge based on user group demand and actual maintenance and development costs. Proposed terms and prices will be disclosed in advance. Paid renewal requires explicit acceptance. There is no automatic charge or obligation to renew. Issued terms and prior accepted commitments are honoured. Optional support is separate.

Renew or export before the 720 powered on hour cutoff. Ordinary processing, administration, customer data access, and exports stop after that cutoff. Data is retained. This allowance is not 30 calendar days.

The current issued 12 month software licence term costs US$0 from the signed issue date. Each independent installation must be registered and may include its approved cluster nodes.

Initial registration after setup and renewal after term expiry each have a 720 powered on hour allowance. Normal use remains available during that allowance.

After it ends, only sign in and the registration, renewal, activation, and necessary identity recovery functions remain. Data is retained, but ordinary access and exports are unavailable.

Optional support

Paid support is separate. No support purchase is required to use, register, activate, or renew Pūnaha.

Next step

Read Register and renew an installation.

Before you start

Choose the supplied 0.1 RC1 package for the intended operating system. Verify its manifest, public certificate, and executable version. Prepare a usable TPM 2.0 or vTPM.

Prepare the database server and any required model files or external storage separately. The native installer does not install a database server.

Install and start

1. Follow the Windows MSI guide or the Linux package guide.
2. Read and accept the bundled licence before installing.
3. Choose Primary for a new independent installation, or Node for an existing cluster.
4. Set the displayed service and listener options.
5. Finish installation and open the supplied browser address.
6. On a Primary, select the database provider during first setup and verify the first System Owner.
7. Open Registration & licence to register the installation.

Check the result

The managed service should run. A new Primary should show first setup. A Node should follow the existing Primary's joining process.

After setup, check service readiness and the registration state before relying on normal work.

Command line development

Commands such as punaha migrate and punaha serve --services=all remain useful for controlled development. Do not substitute them for the packaged installation lifecycle.

If Pūnaha does not start

Read the first installer or service error. Check TPM usability, disk space, ports, and the selected database provider. Do not repeatedly restart without saving the useful error.

Next step

Continue to Set up Pūnaha for the first time and Choose and prepare the databases.

Before you start

Use the supplied x64 Windows RC1 folder and its matching verification files. The MSI checks Windows 11 or Windows Server 2022 or later, administrator approval, disk space, and usable TPM 2.0 or vTPM.

An accepted prerequisite check does not replace the host qualification recorded for that package. Prepare your database server, model files, and any external storage separately.

Install the package

1. Verify the package manifest and publisher certificate through your approved delivery process.
2. Open the MSI. Read and accept the bundled licence for yourself or an organisation you can represent.
3. Choose Primary for a new independent installation. Choose Node to join an existing installation.
4. For a Node, choose the required services. A frontend on a Node also requires Control.
5. Choose the displayed frontend, API and private cluster ports. Independent listeners on the same machine need different available ports.
6. Review the choices and install. Allow the managed service to start.
7. Open the supplied frontend address. Complete browser setup for a Primary, or follow the existing Primary's node joining process.

Check the result

The installed executable must report 0.1.0-rc.1. The service should run and the expected setup page should open. Database selection happens in browser setup, not in the MSI.

If installation stops

Read the first installer error. Check TPM readiness, free disk space, and port use before retrying. Do not clear the TPM of an existing installation as a troubleshooting shortcut.

Next step

Read Finish first setup. For an existing installation, read Upgrade or remove Pūnaha.

Before you start

Use the RC1 folder for the exact distribution and architecture. Do not treat a DEB or RPM file as proof of support for every related distribution.

The package requires TPM 2.0 or vTPM and its declared service and runtime dependencies. Prepare the database server and model files separately.

Install the supplied package

1. Read the platform instructions and verify its manifest with the supplied public certificate.
2. Review the exact bundled licence and privacy notice before accepting. Keep their versions and hashes with the installation record.
3. On an Ubuntu desktop with the supplied graphical installer, open the wizard and choose Primary or Node, services, and ports.
4. On a server, use the supplied distribution package instructions and package manager. Provide the documented installation choices before starting setup.
5. Allow the operating system to request administrator approval. Never enter that password into a Product page or support message.
6. Check the systemd service. Open the frontend for Primary setup, or use the existing Primary to enrol a Node.

Unattended licence acceptance

The Linux package accepts PUNAHA_LICENSE_ACCEPTED=1 only as an explicit installer acceptance choice. Read the bundled terms first. It does not register or activate the installation.

Installation and later registration acceptance are separate receipts. A new legal version must not overwrite a historically accepted version.

Check the result

Verify the installed Product version is 0.1.0-rc.1 and the expected service starts. Preserve the package, installation receipt, and verification files.

If the package cannot continue

Check the reported dependency or TPM error. Do not bypass the prerequisite or substitute another distribution's package. Treat unqualified upgrade paths as pending acceptance.

Next step

Read Choose and prepare the databases and Finish first setup.

Before you start

RC1 includes MySQL, PostgreSQL, and Microsoft SQL Server providers. Confirm the exact engine version and deployment family against your package's acceptance evidence.

A provider implementation is not a blanket support claim for Linux, Azure SQL Database, Azure SQL Managed Instance, or every server version.

Prepare three logical databases

1. Open first setup on the new Primary and select one provider.
2. Use separate Control, Workflow, and AI databases. All three must use the same provider.
3. Enter each database host, port, and logical name. The defaults are punaha_control, punaha_workflow, and punaha_ai.
4. Choose existing accounts or automatic provisioning. Review any replacement warning before confirming.
5. Use separate runtime and migration accounts with the minimum required rights.
6. Configure trusted TLS for remote connections and run every database test.
7. Continue only after all three tests pass.

Understand replacement and provider choice

Automatic provisioning may replace the exact named databases or their tables. Azure SQL Database resources must already exist. Never point a replacement operation at unrelated data.

The provider becomes fixed when setup commits it. An additional Node inherits that choice. Changing an environment value does not migrate an existing installation to another engine.

Check the result

Readiness reports the provider and the Control, Workflow, and AI dependencies. A Connection to an external database is separate from Product persistence support.

If validation fails

Check the selected server family, firewall, certificate identity, database existence, and account rights. Keep secrets out of logs and screenshots. Do not disable certificate verification to hide a remote TLS failure.

Next step

Continue to Finish first setup. Plan a coordinated backup and restore.

Before you begin

Install a new Primary and open its setup address. Prepare MySQL, PostgreSQL, or Microsoft SQL Server according to the selected package's acceptance evidence.

Have the three logical database locations ready. Choose local sign in with an authenticator or your organisation's OpenID Connect provider for the first System Owner.

Complete the setup

1. Start one temporary setup session in a single browser.
2. Choose one database provider and prepare separate Control, Workflow, and AI databases.
3. Test the runtime and migration accounts for all three databases.
4. Choose and verify the first System Owner.
5. Finish setup and follow the restart instruction shown.
6. Sign in and open Registration & licence.

Database choice

The provider becomes fixed when database setup is committed. Additional Nodes inherit it. Read Choose and prepare the databases before confirming any automatic provisioning replacement.

Verify the System Owner

A local owner needs a password of at least 12 characters and an authenticator app. Complete the current code check and save recovery codes privately.

For organisation sign in, register the exact callback displayed for the public setup address. Complete sign in as the identity that should own the installation.

Check the result

First setup should no longer be available. The verified owner should be able to sign in. The 720 powered on hour initial registration allowance now applies.

If setup cannot finish

Continue in the browser that owns the setup session. If recovery is needed, use punaha setup-code --valid-for=15m on the server and follow the displayed instructions.

Check failed database tests, authenticator time, or the exact OIDC callback before retrying. Starting setup alone does not create an administrator.

Next step

Register the installation, then create a tenant.

Sign in

The sign in page shows the methods that your administrator has enabled.

For a local account, enter your email address and password. You may also need a code from your authenticator app. For organisation sign in, Pūnaha sends you to your identity provider.

Accept an invitation

1. Open the invitation link from your administrator.
2. Check the tenant name and your account details.
3. Complete the sign in steps.
4. Open the tenant after you accept the invitation.

Use recovery codes safely

Keep recovery codes away from the Pūnaha server. Do not send passwords, login codes, or session details to support staff.

If you cannot sign in, contact an administrator through your organisation's normal support process.

Links do not give access

You can save a link to a page and open it after you sign in. The link does not give you permission. Pūnaha still checks your access to the tenant, item, and action.

Supported browsers

Use the current or previous main version of Chrome, Edge, Firefox, or Safari.

• Chrome works on Windows, macOS, Android, and ChromeOS.
• Edge works on Windows and macOS.
• Firefox works on Windows and macOS.
• Safari works on macOS and on the current or previous main version of iOS and iPadOS.

Accessibility support

Pūnaha aims to meet WCAG 2.2 level AA. Tests cover keyboard use, screen readers, 200% and 400% zoom, forced colours, reduced motion, and increased contrast.

The app includes light, dark, high contrast, low glare, and colour friendly themes.

Older browsers

Pūnaha needs modern browser features. If an important feature is missing, the app asks you to update your browser. It does not hide the problem.

Live workflow updates

Pūnaha normally shows workflow updates as they happen. If the live connection stops, the browser checks the saved workflow status instead. You do not lose the saved run history.

Platform and tenant areas

Platform administrators can see Tenants, Operations, Audit, and Settings.

Inside a tenant, you may see Overview, Operations, AI, Workflows, Cases, Connections, Chat, People, Settings, Audit, and Logs.

Why your menu may look different

Pūnaha only shows areas and actions that you can use. A missing menu item usually means that you do not have access to it.

Check where you are

1. Check the tenant name before you change anything.
2. Use the main menu to open an area.
3. Use the links above the page title to go back.
4. Open your account menu to change your personal settings.

Saved links

You can save a link to a page. The link does not give you access. If Pūnaha blocks the page, ask an access administrator to check your access to that item.

Open your settings

Open your account menu and choose Preferences. These settings only affect your account.

Choose a theme

You can choose light, dark, high contrast, low glare, or colour friendly colours.

Choose the option that is easiest for you to read.

Use your browser settings

Pūnaha follows your browser settings for reduced motion and higher contrast. It also supports Windows forced colours.

If a setting does not work

Make sure you are using a supported browser. Update the browser if Pūnaha asks you to do so.

Before you start

Choose the knowledge database that should hold the documents. Make sure you have access to create documents and search the database.

Use documents that your organisation has approved for this purpose.

Create a knowledge database

Open AI, then choose Knowledge. Create a database and choose an embedding model. You may also need to choose a search method.

You only see the choices that you have permission to use.

Add files

1. Open the knowledge database.
2. Choose up to 20 supported files.
3. Start the upload.
4. Wait while Pūnaha reads and indexes the files.

Pūnaha shows each step, such as waiting, reading, splitting text, creating embeddings, and finishing.

Check the upload result

Each file should show that processing finished. Open the document details and check the name, state, and recorded processing information.

If the same content is already present, read the result before uploading it again.

Leave the page if you need to

You can go to another page while the files are being processed. When you return, Pūnaha shows the saved progress.

Search the knowledge

1. Open Test retrieval.
2. Enter a question about a fact in the uploaded document.
3. Choose Search knowledge.
4. Read the returned stored passages.
5. Compare each useful passage with the source document.

A useful result should contain the correct passage and a source reference. A match score alone does not prove that the answer is correct.

If a file does not finish

• Pūnaha may reject a file that is encrypted, damaged, empty, or not supported.
• A file that contains only images may have no readable text.
• If processing fails, record the file name, document ID, job ID, time, and message.
• Check Operations and logs before you upload the file again.

Delete with care

You need separate access to delete a file or the whole database.

Deleting a file also removes its text, vectors, and processing records. Deleting a knowledge database asks you to type a confirmation.

Next step

Use the database in a draft workflow. Read Build a workflow before you publish it.

Control processing

Open document details to distinguish preparation, capacity waiting, generation, and embedding. Read the original failure and actual processing node.

Use Stop, Assign, and Resume when needed. Wait for Paused before changing an active job destination.

Before you start

Chat runs a published workflow. You need access to Chat, that workflow, and the models, knowledge, or Connections it uses.

Start a chat

1. Open Chat in the intended tenant.
2. Choose a published workflow.
3. Enter your question or instruction.
4. Optionally attach supported documents and review the selected files.
5. Send the message and follow the saved result or waiting state.

Attach documents

A message accepts up to three TXT, MD, CSV, JSON, PDF, or DOCX files. Each file can be up to 1 MiB. The combined originals can be up to 2 MiB.

PDFs need searchable text. Encrypted, empty, malformed, and unsupported files are rejected. Extracted text and the full message also have bounded limits.

Remove unwanted files before sending. A rejected submission keeps the draft available for correction. These limits are separate from Knowledge uploads.

Understand where the text goes

The selected workflow receives the extracted text as reference input. It may pass that text to its configured model or Connection. Attaching a file does not automatically add it to shared Knowledge.

The run retains extracted text and file metadata, not the original binary for download. Follow up messages can retain the earlier document context.

User facing Chat run access is limited to the creator within the tenant. This is not an encryption boundary against system administrators or a workflow configured to send content elsewhere.

Follow waits and approvals

Read the displayed wait type. Only an approval wait asks for a decision. Other waits can finish through background work. Follow the immutable instructions shown for the approval.

Cancel or reconnect

Cancel stops further work when available. It does not erase an accepted saved chat. If live updates stop, reopen the saved run and check its state before sending again.

Next step

Read Create and search knowledge for shared document indexing, or document formats and limits.

Find a workflow

Open Workflows to see the workflows that you can use. Folders and stars help you organise the list. They do not change access.

Start a workflow

1. Open a published workflow.
2. Read the information it needs.
3. Enter the required information.
4. Choose Run.

Pūnaha saves the workflow version, progress, events, and results.

Follow the progress

Some steps can run at the same time. The run page shows the current state and the events that have already been saved.

Complete a task or approval

A workflow can stop and wait for a person. Only people with the right access can complete the task or make the decision.

If you cancel a run, Pūnaha keeps its history.

Read the current run state

Distinguish a human approval from a scheduled or background wait. Read the saved instructions before a decision. Reopen the run history after a lost live connection.

About cases

A case follows a published case type. The case type defines its stages, tasks, requirements, and files.

Find your work

Open Cases or the work queue. You will only see the case work that you can access.

Access to view a case does not always include access to work on it.

Update a case

1. Open the case.
2. Read its current stage and requirements.
3. Open the task that you need to complete.
4. Save your work.

Pūnaha records important case events in order.

Case files and new versions

Case files have their own access checks. A new case type version does not change open cases by itself.

An administrator can first check how a move to the new version will affect a case. The administrator can then move the case if it is safe.

Typed information and changed records

Enter dates, numbers, choices, and other case fields in the type requested. Refresh after a concurrent edit conflict instead of overwriting another person.

Suspended cases need the permitted resume action. Listener and timer work follows the case plan and current runtime state.

One full Product

Pūnaha permits personal and organisational use. The current issued 12 month software licence term costs US$0 from the signed issue date. Optional paid support is separate and is not required for registration or renewal.

You may use multiple versions and independent installations under their issued terms. Register each independent installation. Its approved cluster nodes belong to that installation.

Future renewal pricing is undecided and may include a charge based on user group demand and actual maintenance and development costs. Proposed terms and prices will be disclosed in advance. Paid renewal requires explicit acceptance. There is no automatic charge or obligation to renew. Issued terms and prior accepted commitments are honoured. Optional support is separate.

Renew or export before the 720 powered on hour cutoff. Ordinary processing, administration, customer data access, and exports stop after that cutoff. Data is retained. This allowance is not 30 calendar days.

Before you start

Finish first setup and sign in as System Owner. Open Registration & licence on the current configuration authority. The configured Support service must be available for approval.

Register and activate

1. Start registration and review the installation and owner information.
2. Continue to the configured Support portal. Register for yourself or an organisation you are authorised to represent.
3. Review and accept the displayed licence version. Treat optional email sharing as a separate choice.
4. Submit the request and follow its approval status.
5. When activation is available, return to Pūnaha and apply the verified activation.
6. Check the active term and the next required action.

Submitting a request does not complete activation. Use the file exchange when the Product cannot reach Support.

The 720 powered on hour allowance

Initial registration has 720 powered on hours after first setup. Each expired registered term has the same 720 hour renewal allowance. Normal use is available during the allowance.

Time with the TPM powered off does not count. Stopping only the Product service does not stop the host TPM clock. Sleep, standby, and VM suspension depend on the platform's TPM behaviour.

Ordinary restarts and computer date changes do not reset or extend the allowance. Adding nodes does not multiply it. Repeated requests and membership updates do not replenish it.

The registered term has signed calendar validity. The allowance is a fixed Product rule. It is not customer editable and has no separate calendar grace period.

Renew the term

Renewal becomes available during the 60 days before expiry. Choose Renew online or Renew using a file. Apply the approved activation and check the new term.

When the allowance ends

Only sign in, registration, renewal, activation, and necessary identity recovery remain available. Normal APIs, tenant access, background processing, exports, and unrelated administration stop.

Expiry does not delete customer data. A valid new activation restores normal use. A clock or protected state problem may also restrict access until repaired.

Check the result

Confirm registration is active and ordinary work is available. Retain the immutable acceptance receipt and its exact document versions and hashes.

If registration cannot finish

Read Fix registration and renewal problems. Do not reset clocks, delete allowance records, or clear the TPM to obtain more time.

Before you start

You need a separate connected device, the configured Support portal, the owning account, and an approved way to transfer files. The portal and signing service must be available.

The 720 powered on hour allowance also applies offline. An isolated installation is not exempt from registration or renewal.

Exchange the files

1. Open Registration & licence as System Owner on the current authority.
2. For initial registration, generate the offline request. For renewal, choose Renew using a file.
3. Transfer the encrypted request to the connected device. Keep its filename and bytes unchanged.
4. Open the portal address shown by Pūnaha. Sign in to the owning account and submit the request.
5. Review the current terms and complete the required approval.
6. Download the approved encrypted activation and return it to the original installation.
7. Import it through the matching Product action and check the result.

Check the result

Pūnaha verifies the request, installation binding, signature, serial, and validity. The status must show the new active term. A downloaded or submitted file alone is not proof of activation.

If an import is rejected

Use the activation for this exact request and installation. Old serials, wrong recipients, and expired activations are rejected. Correct a computer date error before requesting a new time limited file.

Keep the installation's protected state. Repeated exports do not reset the allowance. Record only the request reference and safe error code when asking for help.

Next step

Read Registration and renewal for timing, restricted access, and acceptance receipts.

Before you start

Prepare DNS, trusted HTTPS certificates, and gateway routes for every browser address. An origin is a scheme, hostname, and optional port without a path.

Configure the addresses

1. As System Owner, open System Configuration, then Public addresses and CORS.
2. Add each frontend origin and its browser facing API origin. Multiple frontend addresses may map to the same installation.
3. Open Authentication connections and edit each OpenID Connect profile.
4. Add the matching frontend and callback mappings. Register each exact callback with the identity provider as a confidential Web application redirect URI.
5. Under Additional browser API access (CORS), add only approved integration origins. Leave session cookies off for bearer token clients.
6. Save and reload each frontend.

Check the result

Test sign in from every public address and confirm the returned browser stays on its intended frontend. A private cluster address must not become the public sign in destination.

The API still checks authentication, tenant access, and exact resource actions. Allowing an origin does not grant Product permission.

If sign in returns to the wrong place

Compare the browser origin, mapped API origin, proxy route, and registered callback exactly. Check HTTPS trust on the browser and servers. Do not use a wildcard to hide a mapping error.

Next step

Read Authentication and access and Add and manage nodes.

Before you start

Sign in as a platform administrator. Confirm the approved tenant name and address with your organisation.

Open the tenant list

Open Platform, then choose Tenants. This page shows each tenant and its current state.

Create a tenant

1. Choose Create tenant.
2. Enter the approved tenant name.
3. Enter the address that people will use to identify the tenant.
4. Review both values.
5. Save the tenant.
6. Open the new tenant.

Check the result

The new tenant should appear in the tenant list. Its overview should open without showing information from another tenant.

Add the tenant owner. Then set up sign in, storage, models, and access before people start work.

Check the tenant name

Always check the tenant name before you change people, data, or settings.

If the tenant is not created

Read the message shown by Pūnaha. Check the name and address, then confirm that another tenant is not already using the same identity.

Do not change an existing tenant to work around a failed save unless that change is separately approved.

Next step

Continue to Invite a person and give access.

Delete a tenant

Deleting a tenant removes important data. Save any records that your organisation must keep. Complete your backup and approval process first.

Pūnaha asks you to type a confirmation before it deletes the tenant.

Open People and access

This page shows members, invitations, groups, permissions, and access reviews.

Invite a person

1. Choose Invite user.
2. Enter the person's correct identity details.
3. Choose the right sign in method.
4. Send the invitation.
5. Give the person only the access they need.

Use groups

A local group is managed in Pūnaha. An external group gets its members from your identity provider.

Remember the access step

Adding a person to a tenant does not give them access to product areas. Add their access separately.

Removing a person from one group does not remove access from other groups or direct assignments.

Before you start

Check the tenant name. Confirm the person's email address and sign in method.

Write down the exact product area, item, and actions they need. Decide whether the access needs an end date.

Send the invitation

1. Open People and access.
2. Choose Invite user.
3. Enter the person's correct email address.
4. Choose the correct sign in Connection.
5. Review the details.
6. Send the invitation.

Ask the person to accept

The person should open the invitation and check the tenant, email address, sign in Connection, and expiry time.

They must continue with the account that matches the invitation. After they finish, their membership should appear as active.

Give the required access

1. Open Permissions.
2. Select the person.
3. Choose Add access.
4. Choose the product area and item type.
5. Choose a named item when possible.
6. Add each required action.
7. Set the start and end dates when needed.
8. Review the access and save it.

Check the result

1. Keep the person selected in Permissions.
2. Open Check access.
3. Choose the exact item type, named item, and action.
4. Run the check.
5. Check one action that should be allowed.
6. Check one action that should stay unavailable.

The result should explain the final Allow or Deny and the access that caused it.

If it does not work

• An expired, used, revoked, or incorrect invitation cannot be accepted. Send a new invitation only after you check the cause.
• A person must use the account named by the invitation.
• View does not include Search, Run, Create, Update, Work, Publish, or Delete.
• A Deny can block an Allow.
• Another group or direct assignment may also affect the result.

Next step

Read Manage people and groups for shared access. Use Fix an access problem when the final result is not what you expected.

Open Permissions

Open People and access. Then choose Permissions.

Give access

1. Choose a person, group, or service.
2. Choose the product area.
3. Choose the type of item.
4. Choose the named item when possible.
5. Choose each action the person needs.
6. Set a start date and an end date if needed.
7. Save the access.

Actions are separate

View does not include Search, Run, Create, Update, Work, Publish, or Delete. Add each action that is needed.

Use the smallest access

Choose one named case, model, or knowledge database when you can. Avoid access to all items unless the person truly needs it.

Review access

Use Access reviews to check old or wide access. Record whether to keep, change, or remove each item.

Write down the problem

Record the tenant, person, item, action, time, message, and request ID. Do not collect passwords, login codes, or secret keys.

Check the exact action

1. Open People and access.
2. Choose Permissions.
3. Select the person or service.
4. Open Check access.
5. Choose the item type.
6. Choose the named item.
7. Choose the action that failed.

Common reasons

• The menu is missing because the person does not have the required action.
• A saved link does not give access.
• View access does not include Search, Run, or Work.
• A Deny rule can block an Allow rule.
• Another group may still give access after one assignment is removed.

If another administrator changed it

If you see ACCESS_GRANT_CHANGED, reload the page. Read the new details before you try again.

Before you start

Choose an approved local model or model provider. Make sure you have permission to manage models and create knowledge databases.

Prepare one small document with information that is safe to use for a test.

Prepare the model

1. Open AI, then choose Models.
2. Choose an approved model provider or the local model runtime.
3. Add the model details required by that provider.
4. Test embedding and text generation separately when both are needed.
5. Enable the model only for the work it can perform.

Create the knowledge database

1. Open AI, then choose Knowledge.
2. Choose Create database.
3. Enter a clear name, title, and purpose.
4. Choose the prepared embedding model.
5. Choose the search methods needed for this information.
6. Create the database.

Add and test one document

1. Open the new database.
2. Upload the safe test document.
3. Wait until processing finishes.
4. Search for a fact that appears in the document.
5. Open the returned passage and check it against the source.

Check the result

The model should be ready for its enabled work. The document should show as finished. The test search should return the correct stored passage.

If it does not work

• If no embedding model is available, check the model state and your access.
• If the document is rejected, check its type, size, encryption, and readable text.
• If processing fails, record the document and job details before trying again.
• If search returns the wrong passage, check the source document and search methods before adding more documents.

Next step

Read Upload and search knowledge for daily document work. Read Run local AI models for local model setup.

Capacity and document work

Configure generation and embedding separately. Read model scheduling and document processing controls before changing a busy node.

Before you start

Confirm the system address, Connection type, sign in method, and network rules with the system owner.

Keep the password, token, or key in an approved secret store until you enter it in Pūnaha.

Open Connections

A Connection stores settings for email, an API, or a database. A workflow can use the Connection without storing its password.

Add a Connection

1. Choose Add Connection.
2. Enter a clear name and purpose.
3. Choose the type.
4. Enter the server address.
5. Choose the sign in method.
6. Enter the login details.
7. Check the secure connection and allowed host settings.
8. Save the Connection.

Test the Connection

1. Choose Test on the saved Connection.
2. Wait for the result.
3. Read the complete message.
4. If the test succeeds, check the time and test message saved on the card.
5. Give access only to the people and services that need it.

A successful test proves that the saved Connection worked at that time. It does not prove that every action is allowed.

Check the result in a solution

Use safe sample information in a draft workflow. Check the result before you publish the workflow.

Protect passwords and keys

Do not put passwords in a workflow, page address, screenshot, or normal log.

A successful test only proves that the Connection worked at that time. It does not prove that every action is allowed.

If the test fails

1. Read the saved test message.
2. Check the server address and port.
3. Check the sign in method and secret.
4. Check the secure connection setting.
5. Check the allowed host and private network rules.
6. Test again only after you change the likely cause.

Change a Connection

Check which published workflows use it. If a password is exposed, disable access and change the password at its source. Then update and test the Connection.

Next step

Use the Connection in a draft workflow journey. Keep it out of the published workflow until the test succeeds.

Choose the right settings page

Platform settings apply to the whole installation. Tenant settings apply to one tenant. Personal settings apply only to one person.

Change a setting

1. Check whether you are on the platform or tenant page.
2. Open the correct group.
3. Read the current value and where it comes from.
4. Change only the setting you need.
5. Save it.
6. Check the value that Pūnaha shows after saving.

Platform settings

The platform page also includes runtime, sign in, storage, models, logs, and environment information.

Restart notices

Some settings need a service restart. Restart only when the page tells you to. Keep passwords and secret keys out of screenshots and support messages.

RC1 shared and node settings

Use the current configuration authority for shared changes. A joined node can change only its permitted local overrides.

Read public addresses and CORS and model scheduling. A saved remote value is not proof that an unreachable node has applied it.

Use clear responsibility boundaries

Your organisation decides who fills each role. Keep the roles separate enough for important changes to be reviewed.

Check the scope before a change

1. Confirm whether the change is for the platform or one tenant.
2. Confirm the named person who owns the result.
3. Confirm who can approve the change.
4. Confirm who will make it.
5. Confirm who will check the result.

Keep product access separate from administration

Permission to manage access does not automatically give permission to use an item. Permission to operate a service does not automatically give access to customer work.

Use a handover record

Record the tenant, approved purpose, affected items, person making the change, checker, time, result, and request or audit ID. Do not place passwords, keys, tokens, or customer data in this record.

Related tasks

Read Manage tenants, Review access, and Make a safe production change.

Before you start

Confirm the tenant, people or groups, resource types, and review period. Name the person who will decide whether each item is still needed.

A review covers the assignments selected by its criteria. It does not prove that unrelated access is correct.

Create the review

1. Open People and access.
2. Choose Access reviews.
3. Create a review.
4. Choose clear criteria that match the approved scope.
5. Check the number of matching direct assignments.
6. Set the reviewer and due date.
7. Start the review.

Decide each item

• Keep means the current assignment is still correct.
• Change means the person still needs access but the item, actions, or dates need correction.
• Remove means the assignment is no longer needed.

Read the resource, actions, effect, dates, and evidence before deciding.

Complete the review

1. Resolve every pending item.
2. Check changed actions and dates.
3. Refresh if another reviewer changed the review.
4. Complete the review.
5. Confirm that the review reached its final state.

Completion is one operation. Pūnaha does not apply only part of a completed review.

Check the result

1. Use Check access for an action that should remain allowed.
2. Check an action that should now be unavailable.
3. Check the permission ledger and audit record.
4. Keep the approved review evidence under your organisation's rules.

If the review cannot finish

Look for a pending item, a change made by another reviewer, an invalid proposed action, or missing review management access. Read Fix sign in, invitation, and access problems.

Next step

Set the next review date according to your organisation's policy. Do not assume that completing one review makes all future access correct.

Start with one server

For development, you can run all Pūnaha services together.

punaha serve --services=all

Split the services when needed

Check the servers

Platform Operations shows the servers and their work queues.

Connect Workflow to AI

A Workflow server needs access to AI services. It can use AI in the same program or connect to a private AI address. Pūnaha will not start a Workflow server if neither option is ready.

Start with a working Primary

Use a new Primary for each independent installation. Add approved Nodes when capacity or service placement requires them.

Choose public and private addresses

Map each public frontend to its browser facing API address. Use trusted HTTPS and explicit OIDC callbacks. Keep databases and private cluster listeners away from public traffic.

Read Public addresses and organisation sign in.

Add more servers

You can run more than one Workflow or AI server. Each node needs the same installation identity, provider choice, approved configuration, and access to the required storage.

Follow Add and manage cluster nodes. Database leases distribute queued work. Forwarding to a ready peer is not a guarantee against every machine failure.

Use the current authority

Make shared changes on the current configuration authority. Check node readiness before a transfer or service change. Joining nodes does not extend the 720 powered on hour allowance.

Upgrade the installation

Use a qualified upgrade path and one coordinated recovery checkpoint. Update every participating node before depending on a new private routing feature.

Read Upgrade or remove Pūnaha and Prepare shared storage.

Before you start

Begin with a working Primary and a usable registration allowance or active term. Prepare private connectivity, matching builds, the chosen database provider, and shared storage.

A single server does not need an active private cluster listener. Internal node certificates are separate from browser facing HTTPS certificates.

Add a node

1. Open Registration & licence on the Primary and choose Prepare for additional nodes.
2. Configure the private cluster address and port shown by the Product. Allow that port only between intended nodes.
3. Install the matching RC1 Node package on the other machine and select its services.
4. Follow the node enrolment instructions to submit its join request to the installation.
5. On the current authority, review the requested identity and services before approving the join.
6. Wait for the Node to receive its approved configuration and become ready.
7. Review trusted nodes and any required signed node inventory update.

Check the result

Confirm the Node is approved, reporting, and ready for each selected service. Reachability alone does not prove membership, licence admission, shared storage access, or model readiness.

The installation can run more than one Workflow or AI server. Work ownership and service routing still depend on the current ready node set.

Manage authority and service changes

Use the current configuration authority for shared settings and registration. Review the target readiness before a supported authority transfer. Authority transfer retains the installation allowance.

Service switch off requires another approved and ready process for the same role. Active work can be interrupted. Check saved jobs and recovery after a controlled reload.

If a node cannot connect

Check the displayed destination, private port, firewall, current certificate, node approval, and build. Do not expose the private listener publicly or bypass certificate checks.

Remove or recover a node

Revoke a Node before uninstalling it. Remove Nodes before the Primary. Use the recorded recovery path for a permanently lost node. Do not erase membership history or protected identity files.

After registration allowance expiry, general node administration is unavailable. Restore registration before unrelated cluster changes.

Next step

Read Prepare shared storage and Upgrade or remove Pūnaha.

Keep the three roots separate

On Windows these sit beneath the selected installation folder. Ubuntu uses /var/lib/punaha-local, /var/lib/punaha-security, and /srv/punaha-cluster.

Choose the storage type

Filesystem, S3 compatible, and Azure Blob storage have different connection and permission requirements. Check the selected adapter for documents, indexes, and logs separately.

GGUF model weights need a filesystem path available to the Product service. Azure Blob credentials do not mount Azure Files. S3 object access does not provide a model filesystem.

Prepare and test

1. Create a private location reserved for this installation.
2. Give each approved node's service identity the required access.
3. Configure the selected destination through the current authority. Enter credentials only into protected Product fields.
4. Test from every node as its service identity, not only as your desktop user.
5. Confirm document access, index readiness, model readability, and logs separately.

Model caches and temporary files

Model workers use verified node local copies. Allow space for the model and its staging reserve. Cache hits still verify the authoritative source, so a cache is not an offline storage replacement.

Only clean old model cache versions while all local model workers are stopped. Never treat the Security directory as a cache.

If storage fails

Check the exact path, protocol, service identity, and node. A successful HTTPS test to Azure does not prove SMB access. Changing a storage setting does not migrate existing data.

Next step

Read Plan storage and backups.

Use the two health checks

• /health/live tells you that the program is running.
• /health/ready tells you that the program is ready to receive work.

Use Ready for traffic

A server can be running but not ready. It may still need a database, an update, or an AI service.

Set the load balancer to use the Ready check.

Know the healthy result

Live should succeed for each running process. Ready should succeed only when the service can accept its normal work.

System operations should show the expected servers as ready. New test work should leave the queue and reach a final state.

Protect the AI service

Only Workflow servers and trusted administrator networks should reach the private AI service.

Retry with care

Retry a request only when the connection failed or the error says it is safe. Do not repeat every model request automatically.

If a service is not ready

Keep it out of normal traffic. Follow Fix service readiness and storage problems.

Before you start

Record what the person was trying to do. Record the tenant, time, item, message, and request or run ID.

Do not collect passwords, tokens, private keys, or customer documents that are not needed for the check.

Find the work in Operations

1. Open System operations for the whole installation or Tenant operations for one tenant.
2. Choose the smallest useful time range or work group.
3. Find the active, waiting, or failed item.
4. Record its service, state, item ID, job ID, run ID, or request ID.
5. Read the message before you change anything.

Follow the item into the logs

1. Open Operational logs.
2. Use a short time range around the failure.
3. Enter the tenant and the best available ID.
4. Read the events in time order.
5. Find the first event that explains the failure.
6. Record the service and message.

Check for an administration change

Open Audit history when the problem may follow a change to access, settings, a Connection, a model, or another managed item.

1. Use the same tenant and time range.
2. Filter by person, action, resource, or request ID.
3. Check the result of the change.
4. Compare its time with the first failure.

Choose the next action

• Fix a setting only when the evidence identifies that setting.
• Restore access only after Check access confirms the missing action.
• Test a failed Connection before a workflow uses it again.
• Restart a service only when its state or logs show that a restart is needed.
• Retry work only when the operation is safe to repeat.

Check the result

Return to Operations after the change. Confirm that the service is ready and that new work reaches a final state.

Keep the original IDs and the change record when your organisation needs evidence of the investigation.

If the cause is still not clear

Keep the current evidence. Record the exact version, time range, service, tenant, IDs, and messages.

Do not make several unrelated changes at once. Each change makes the original cause harder to find.

Next step

Read Use the Operations pages and Use logs and audit records for more detail.

Choose a view

System operations shows the installation. Tenant operations shows the selected tenant's work. Check your selected tenant and node before taking action.

Read the work state

Separate queued work, capacity waits, active processing, stop requested, paused work, and terminal results. A model call can finish while its document still needs more stages.

Control a document

Use Stop, Assign, and Resume only for the intended jobs. Wait for stop acknowledgement before changing an active job's destination.

Control document processing explains destination eligibility, progress, and safe recovery.

Investigate a problem

1. Record the tenant, time, processing node, and job or request ID.
2. Read the original failure and recent section outcomes.
3. Check the node heartbeat, storage phase, and model capacity.
4. Compare configured policy with observed execution.
5. Use the related logs and audit records if registration permits ordinary access.

Keep the evidence

Do not repeatedly retry an uncertain action. A saved remote setting does not confirm that an unreachable node applied it.

Registration restriction

When the allowance expires, normal background processing and Operations access stop. Sign in and restore registration before ordinary administration.

Read the processing details

Open the document or its Operations entry. Check its stage, processing node, generation model, embedding model, and latest result.

Copying, verifying, loading, tokenising, waiting for capacity, generating, and embedding describe different work. A completed model call does not mean the whole document is complete.

Stop, assign, and resume

1. Select the intended document job and review its current owner.
2. Choose Stop and enter the required reason.
3. Wait for the state to become Paused. Stop requested is not yet a safe handover.
4. Choose Assign and inspect the destinations and their eligibility explanations.
5. Select an approved ready node with the required models and storage access.
6. Review processing settings if needed, then choose Resume.
7. Confirm the new attempt and destination in its processing details.

Check the result

The source document remains available after a stop. Some stages may restart or reuse saved results. Do not assume every interrupted job resumes from the exact displayed percentage.

A stopped worker must finish cancellation and acknowledge it before active work can move. An unreachable owner or expired lease does not make forced reassignment safe.

Understand GPU evidence

Saved policy, selected accelerator, and observed execution are different. Check the actual backend and fallback reason. A GPU preference or reserved slot does not prove GPU execution.

If work appears stuck

Read the original failure and recent section results. Check the owner heartbeat, storage phase, model capacity, and node connection. Preserve the job and request IDs before another attempt.

Do not keep restarting a service or forcing an assignment while writes may still be active.

Next step

Read Manage model capacity and Fix model and upload problems.

Choose the workload and node

Generation and embedding are separate workloads. Inspect the settings of the selected execution node. CPU, GPU first, and GPU only policies have different fallback behaviour.

GPU first can fall back to CPU when the selected node lacks a usable accelerator. GPU only requires an eligible GPU. A saved setting is not proof of native execution.

Understand the limits

Apply a change

1. Open the relevant Inference or model settings and choose the intended node.
2. Review generation and embedding choices separately.
3. Save one controlled change.
4. Allow healthy node synchronisation to apply it. In progress calls keep their acquired execution settings.
5. Inspect a new call's observed backend and profile.

Read capacity waits

Unavailable or stale GPU measurements reduce automatic admission. Background tests and model fingerprinting can wait while document processing and foreground inference use capacity.

Large models can take time to copy and verify before loading. Storage failure is not fixed by switching the same inaccessible source to CPU.

Next step

Use document processing controls for a specific job. Keep hardware acceptance separate from saved policy.

Know the difference

Operational logs help you find service and request problems. Audit records show important security, access, and administration events.

Search the logs

1. Open Operational logs.
2. Choose a short time range.
3. Enter the tenant and request, run, case, or item ID.
4. Read the events in time order.

Check the audit record

Use Audit history when you need to know who changed access, settings, or another important item.

Protect exported records

Logs and audit records may contain personal or security information. Follow your organisation's rules for access, storage, and sharing.

Do not add passwords or secret keys to a support file.

Open Models

Open AI, then Models. Check the selected server, bundled runtime, model files, Connections, and deployments.

Add a local model

1. Use the runtime supplied with the matching package.
2. Obtain a permitted GGUF model and review its licence and hardware requirements.
3. Upload or select the model file. A file may be up to 32 GB, subject to available storage.
4. Create or select the Embedded llama.cpp Connection.
5. Discover the model and enable the intended generation or embedding deployment.
6. Test the intended workload with safe input.

Load now and load at startup

Load now requests memory loading on the selected server. Load at startup records a preference for a later start. Neither setting guarantees that memory or storage will be available.

Choose processor policy

Generation and embedding settings are separate. CPU, GPU first, and GPU only policies depend on the selected node's available runtime and hardware.

Inspect the observed backend and fallback reason for an actual call. Saving a GPU preference does not prove GPU execution.

Understand waits

Copying and verifying a large shared model can precede loading. Background tests may yield to production work. A verified local model cache still depends on the authoritative source.

Next step

Read Manage model capacity and GPU policy and Control document processing.

Choose a storage place

Filesystem, S3 compatible, and Azure Blob adapters serve different storage needs. Use the configured destination for documents, knowledge indexes, and logs.

Model weights require a filesystem path accessible to the service. Read Prepare shared storage before joining nodes.

Keep private state separate

Local holds node caches and temporary work. Security holds protected installation and identity state. Cluster holds the shared Product data. Never share the Security root.

A new setting does not move old data

Changing a destination does not copy existing documents or indexes. Plan the migration, access checks, and recovery checkpoint before switching.

Back up Pūnaha

1. Quiesce Product writes under the maintenance plan.
2. Back up Control, Workflow, and AI at the same checkpoint using the provider's tools.
3. Include the corresponding protected installation state and required document, index, model, and log files.
4. Record Product version, provider, database versions, migration histories, and backup time.
5. Protect backup material and verify a restore.

Restore consistently

Restore the same provider and matching installation state. A database connection change does not migrate data or change engines.

Registration recovery must preserve the matching Control allowance record and node checkpoint. Clearing a counter does not create a new allowance.

Next step

Read Verify a backup and restore. Solution configuration recovery is separate from database and business data recovery.

Before you start

1. Name the approved change and its owner.
2. List the affected service groups, databases, storage, tenants, and product areas.
3. Record the current product and database versions.
4. Define the healthy result and the stop point.
5. Define how to reverse the change.
6. Choose a maintenance time and tell affected people.

Create a recovery point

Back up the Control, Workflow, and AI databases at one release checkpoint. Include the required document, model, knowledge, runtime, and log data.

Verify the checkpoint before the change. A list of backup file names is not proof that the data can be restored.

Apply one controlled change

1. Remove affected servers from normal traffic when needed.
2. Pause work only when the approved plan requires it.
3. Apply database updates once with the approved migration account.
4. Apply the intended service or setting change.
5. Start services in the approved order.
6. Do not add unrelated fixes during the change.

Check the healthy result

1. Confirm Live and Ready for every affected service group.
2. Confirm each expected server appears in System operations.
3. Check that queues move and new work reaches a final state.
4. Test sign in and one allowed access decision.
5. Test one safe workflow, case, and knowledge action when affected.
6. Check the logs and audit record for unexpected failures.

Stop or reverse when needed

Stop when an agreed check fails, a required store is unavailable, or data versions do not match. Do not keep sending traffic while the cause is unknown.

Use the approved reverse plan. If it requires a restore, use the matching full checkpoint and verify it on the recovered system.

Record the result

Record the version, change time, people involved, checks, result, issue IDs, and audit or request IDs. Keep secrets and customer information out of the change record.

Next step

Use Verify a backup and restore and Investigate a problem.

Check the RC1 path

Use the exact platform upgrade procedure. Keep the installed database provider fixed and preserve protected registration state.

Before an upgrade

Use an upgrade path qualified for the exact starting build, target package, operating system, and database. RC1 source support is not a guarantee for every older development installation.

1. Record the installed version, package, provider, node roles, and ports.
2. Stop new work under the approved maintenance plan and create a consistent recovery checkpoint.
3. Include all three databases, required shared files, and the corresponding protected installation state.
4. Verify the target package and read its platform instructions.
5. Review how to recover if the target fails readiness.

Keep upgrade separate from removal

A supported MSI upgrade preserves configuration and protected state. The Ubuntu upgrade wizard retains existing choices and saves a protected settings copy. That settings copy is not a database backup.

Same version replacement, downgrade, and incomplete installation recovery need their explicit platform procedure. Do not uninstall first as a shortcut for upgrading.

Check the result

Verify the target version, retained settings, registration status, every node, and service readiness. Check safe workflow, case, document, and sign in journeys before reopening normal work.

If the upgrade fails

Keep the installer evidence and recovery copies. Do not assume the installer automatically restores databases or downgrades safely. Use the approved recovery checkpoint.

Remove an installation

Export and back up required information while normal access is available. Revoke and uninstall additional Nodes before removing the Primary. Review the platform's data removal behaviour before confirming.

Loss of registration does not itself delete data. Expired allowance blocks ordinary exports, so renew first if an export is needed.

Next step

Use Make a safe production change and Verify a backup and restore.

Choose the correct recovery

Open Solution packages, then Versions & recovery. Check which actions the installation offers and which retained versions or backups are available.

Before you start

Confirm the installation, current version, intended target, permissions, and recovery point. Keep an independent coordinated database backup when the change needs one.

Configuration recovery does not roll back business data. It does not provide disaster recovery, repair lost private keys, or move a package to another recipient.

Apply and verify

1. Select the intended installed solution.
2. Review the available retained version or encrypted backup.
3. Choose the required recovery action and confirm the target.
4. Wait for completion. If a pending operation remains, reconcile it before retrying.
5. Refresh the active version and status.
6. Test an allowed execution and check that business history is retained as expected.

If recovery is blocked

Refresh after a concurrent change. Check registration, signed rights, recipient binding, current node revision, and the pending operation.

New execution can be blocked during recovery. Never delete a pending journal or change encrypted backup bytes to force completion.

Next step

Read Verify a backup and restore for installation recovery.

Define the backup set

Include the Control, Workflow, and AI databases from one release checkpoint. Record the Product version and each database version.

Include every file store used by the installation. This can include original documents, knowledge indexes, local model files, runtime files, and retained logs.

Keep the parts consistent

1. Use the approved method to pause or coordinate writes.
2. Capture all three databases at the same checkpoint.
3. Capture the matching file data.
4. Record storage destination names and safe counts.
5. Protect the backup and its encryption material under separate approved controls.

Restore away from production

1. Create a separate recovery system.
2. Use the recorded product version.
3. Restore the three databases and matching files.
4. Apply only the approved recovery steps.
5. Keep the recovered system out of production traffic.

Check the restored system

1. Confirm every required service is Live and Ready.
2. Sign in with an approved test account.
3. Check one allowed and one restricted access result.
4. Open a workflow version and a case without changing production work.
5. Search a restored knowledge database and compare one passage with its source.
6. Confirm the required model and Connection states.
7. Check audit and operational records.

Record pass or fail

A restore passes only when the approved checks succeed and the data belongs to the same checkpoint. Record missing data, wrong versions, failed checks, and recovery time.

Do not replace a production system with a failed or incomplete recovery.

Improve the next backup

Correct the backup list, timing, storage, access, or recovery steps that caused the failure. Create and test a new checkpoint.

Next step

Read Plan storage and backups and Fix log, backup, and restore problems.

Include registration state

Restore the matching protected Control allowance record and node state together. Do not clear the TPM or counter to reset registration.

A new host or lost identity may require the signed identity recovery process. Prove that path in a recovery exercise before relying on it.

Before you start

Write down the information the workflow receives and the result it must return.

Prepare the approved Connections, models, and knowledge databases that the workflow needs. Confirm that you have access to create, update, test, publish, and run the workflow.

Create the draft

1. Open Workflows.
2. Choose Create workflow.
3. Enter a clear name and purpose.
4. Add an Input step.
5. Add the work steps in the order they depend on each other.
6. Add an Output step.
7. Save the draft.

Configure the work

1. Open each step.
2. Choose the prepared Connection, model, or knowledge database.
3. Map the incoming information to the fields that the step needs.
4. Map the step result to the next step.
5. Add a clear error path where work may fail.
6. Save the draft again.

Check and test the draft

1. Run the built in check.
2. Fix every error.
3. Read every warning.
4. Test the draft with safe sample information.
5. Check the result from each important step.
6. Test an expected error path.

The workflow card should show that the draft is ready to test. Keep the sample result as review evidence when your process requires it.

Publish a version

1. Check that every dependency is enabled and available.
2. Check that the people who need the workflow have Run access.
3. Choose Publish.
4. Review the confirmation.
5. Publish the numbered version.

The published version stays unchanged while you work on a later draft.

Run and check the workflow

1. Open the published workflow.
2. Choose Run.
3. Enter the required information.
4. Start the run.
5. Open the run details.
6. Check the final state, events, approvals, and result.

If it does not work

• If the draft check fails, fix the named step and field before testing again.
• If a dependency is unavailable, test its Connection, model, or knowledge database.
• If Run is missing, check the exact workflow and Run action in Permissions.
• If a run fails, keep the run and request IDs. Check Operations and logs before repeating it.

Next step

Read Choose workflow steps for each step type. Read Add safety checks and approvals before using the workflow for important decisions or actions.

Open Workflows

The Workflows page shows drafts and published workflows.

Create the first path

1. Choose Create workflow.
2. Give the workflow a clear name and purpose.
3. Add an Input step.
4. Add the work steps in the order they depend on each other.
5. Add an Output step.
6. Save and check the draft.

Use the editor

The editor shows the steps and the links between them. The links decide the order of work.

Keep passwords out

Choose an approved Connection, model, or knowledge database. Do not copy passwords or keys into the workflow.

Open a workflow

Open the workflow draft, then add the step that matches the work.

Main steps

Choose the simplest step

Use a clear rule when a rule can do the job. Use an AI model only when the task needs it.

Add an approval before an important action that needs a person's decision.

Work in the draft

Your changes stay in the draft until you publish them. An old published version does not change while you edit.

Check the workflow

1. Save the draft.
2. Run the built in check.
3. Fix every error.
4. Test with safe sample information.
5. Check each result and error path.

Publish it

Publishing creates a numbered version. Check that its Connections, models, knowledge databases, and access are ready first.

Check a run

Pūnaha saves the workflow version, state, events, approvals, and results for each run.

If you cancel a run, Pūnaha stops future work but keeps the history.

Start the import

Open Workflows, then choose Import BPMN or DMN.

Check an imported file

1. Import the file into a draft.
2. Read every error and warning.
3. Check paths, decisions, information, people tasks, and error handling.
4. Test common and unusual examples.
5. Export the result.
6. Open it in the other tool if you need to exchange files with that tool.

Do not assume every detail moved

A file can import even when a part needs review. Read all warnings and check any value that Pūnaha created for you.

Standards claim

Pūnaha includes import, export, and checking tools. This does not mean that every formal BPMN, DMN, or CMMN check is complete.

Verify imported decisions

Validate an imported DMN model and test typed inputs before publishing. An accepted import is not proof that every external tool extension or standard construct is supported.

Choose safety checks

Pūnaha can check for harmful language, sexual content, violence, self harm, prompt attacks, and private information.

You can start with a ready made set of checks or choose your own checks.

Choose where to check

You can check information when it enters the workflow, after a search or Connection, before and after a model, and before the final result.

Use clear rules as well

Safety checks do not replace access, field checks, or clear business rules.

Add an approval

Ask a person before an action that is hard to undo, changes another system, spends money, or needs a policy decision.

Give the person enough information to decide. Also say what happens if they reject it or do not answer.

Before you start

Describe the kind of work the case will manage. List the information, people, stages, tasks, requirements, and files it needs.

Confirm that the builder can manage case types. Confirm that the case worker can create or work with cases.

Create the case type

1. Open Cases, then choose Case types.
2. Choose Create case type.
3. Enter a clear name, address, and description.
4. Create the draft.
5. Add the roles and information fields.
6. Add the requirements.
7. Add the stages and work items.
8. Add rules only where they are needed.
9. Save the draft.

Check and publish the case type

1. Open the draft in the case type editor.
2. Check each stage, task, requirement, and field.
3. Run the built in check.
4. Fix every issue.
5. Test the normal path and a difficult case.
6. Choose Publish.
7. Publish the numbered version.

Open a case

1. Return to Cases.
2. Choose Open case.
3. Choose the published case type.
4. Enter the case title.
5. Enter the information required at the start.
6. Open the case.

The new case should show its reference, case type version, current stage, requirements, and available work.

Complete case work

1. Open My work or the case list.
2. Open the case.
3. Read the current stage and requirements.
4. Start the correct work item when it needs a start action.
5. Record the outcome and complete the work.
6. Record evidence for a requirement when needed.
7. Check the case history.

Check the result

The completed action should appear in the case history. The next available work should match the published case type and the information held by the case.

If it does not work

• If Open case is missing, check Create access for Cases.
• If no case type is available, publish a valid case type first.
• If work is missing, check the case worker's Work access and the case rules.
• If a requirement cannot be completed, check the required evidence and the person's access.

Next step

Read Build a case type for more design detail. Read Work with cases for daily case work.

Open Case types

Open Cases, then choose Case types. You can create a case type or import a CMMN file.

Build the case type

1. Give it a clear name and purpose.
2. Add the people or roles involved.
3. Add its stages.
4. Add tasks, requirements, and files.
5. Add rules only where they are needed.
6. Save and check the draft.

Publish a version

Test the normal path and difficult cases. Then publish a numbered version.

Move open cases with care

A new case type version does not change open cases. First use the move preview to see what will change. Move the case only after you check the result.

Check typed fields and timers

Use the correct field types for forms and case file values. Test listeners, timers, suspension, and resume with safe examples before publishing a case type.

Before you start

Use a trusted package, its matching recipient grant, and the required installation permissions. Confirm Product registration, the approved node set, and required services.

Solution package approval and signed rights are separate from the Product licence. An internal package route is not automatically a customer integration API.

Install the solution

1. Open Solution packages and import the unchanged package and matching grant through the offered actions.
2. Run preflight. For an upgrade, select the existing installed solution as the target.
3. Review dependencies, mappings, recipient, protection mode, and any failed checks.
4. Stage the solution and complete the required tests.
5. Request the required approval and wait for its decision.
6. Import or apply the matching signed activation when available.
7. Run the readiness check, then activate the intended version.

Check the result

Open Installed solutions. Confirm the active version, rights, and status. Run one permitted sample workflow or case with safe data.

Importing, staging, approval, and activation are distinct states. None of the earlier steps alone makes the solution active.

If a gate fails

Read the failed check and correct the dependency, permission, node revision, or signed file. Do not edit a signed package or bypass approval.

Package lifecycle behaviour is present in RC1 source. Native installed database acceptance still needs evidence for the selected package and environment.

Next step

Read Recover solution configuration before relying on an upgrade.

Choose the right contract

Use the customer OpenAPI file at /openapi.json. It contains 96 classified customer operations across 73 paths in this RC1 source baseline.

Do not build against a route seen only in the Pūnaha interface or controlled internal contract. An /api/ address does not by itself make an operation supported for customer integration.

Check the lifecycle

Read the Stable or Preview label before choosing an operation. Preview operations may change. Keep the saved contract, Product version, and client version together.

Prepare safe test state

1. Use an isolated development tenant.
2. Create only fictitious identities and records.
3. Grant the test actor the smallest required action.
4. Choose a request ID that contains no personal information.
5. Keep tokens and cookies outside source control.

Make the first request

Start with GET /health/ready. Then sign in using a supported current Product mechanism and read one resource that the actor is allowed to view.

Keep the evidence

Record the HTTP status, stable error code, and returned x-request-id. Do not store passwords, session tokens, customer documents, or unnecessary response content.

Next step

Read Use tenant and access context before a protected request. Use the API overview to choose an API area.

Separate identity, tenant and access

Authentication identifies the actor. Tenant context selects the boundary. Permission checks decide whether that actor can perform the exact action on the exact resource. None of these steps replaces another.

Use this sequence

1. Sign in using a supported Product mechanism.
2. Select the intended tenant through the authenticated session or documented tenant header.
3. Find the resource through its customer operation.
4. Ask an authorised administrator to confirm the exact access through the approved Product action.
5. Perform the business operation.
6. Keep the returned request ID.

Handle a denied request

A resource identifier does not grant access. A matching explicit Deny wins over an Allow. Confirm the tenant, resource type, resource ID, and action before an authorised administrator changes access.

Do not automate Product administration without approval

Tenant, user, licence, node, and Product interface administration routes are not included in the customer contract. Use the approved Product action unless a later release explicitly classifies an administration operation for integration.

Reference

Read the access model. Authorization administration is not in the customer API contract.

Before you start

Prepare a published workflow with safe test inputs. Confirm the actor has View and Run for that exact workflow. A draft or unrelated workflow is not a substitute.

Follow the journey

1. List workflows and find the intended identifier.
2. Read the workflow and confirm its current state.
3. Check the actor's Run access.
4. Start the workflow using the smallest valid input.
5. Read the returned run identifier.
6. Read the run or connect to its server event stream.
7. Handle waiting, completed, failed, and cancelled states.
8. Read the final result before starting dependent work.

Reconnect safely

The event stream reports parsed server events. Do not assume historical replay unless the operation says it is available. After a disconnect, read current run state before deciding whether to reconnect.

Handle an uncertain start

Do not submit the same start request blindly after a timeout. Find the run by the safe identifiers available to the journey, inspect its state, and start a new run only when duplicate work is acceptable.

Reference

Use the Workflows and runs API reference for the exact fields, errors, examples, related operations, and lifecycle.

Chat runs with documents

For runKind: "chat", the run input accepts supported attachments with fileName, contentType, and contentBase64.

Validate the limits in Use Chat. A rejected batch creates no partial run. Normal Chat visibility is limited to the creator in the selected tenant.

93 Preview operations are documented so you can evaluate them, but they may change. Check the lifecycle label before committing an integration.

Use the four documentation parts

Explore API categories

The category names, descriptions, order, and operation membership come from the Product customer OpenAPI contract. They match the groups shown in Swagger.

Check the API health

Start with the Ready health request. It does not need sign in.

curl http://localhost:3001/health/ready

A successful response means that the API is ready to receive work.

Open Swagger if you need it

Swagger is included in the Pūnaha executable. The API address sends you to /swagger/. With the normal development ports, use http://localhost:3001/swagger/.

You do not need Swagger to read the API reference on this website.

1. Choose an API group.
2. Open the request you need.
3. Read its method, address, input, and possible responses.
4. Only try a request when you understand what it will change.

Download the OpenAPI file

The customer OpenAPI 3.2 file is at /openapi.json. Save the file from the exact Pūnaha version and server type you use. The current documentation source digest is 8c568bec762d5d5568af9f763ae9a39eb50c6d820f83e8fb1f0273b7dae773b7.

Build an API client

1. Create the client from the saved OpenAPI file.
2. Choose how the program will sign in.
3. Give it only the access it needs.
4. Test successful requests and errors.
5. Test the client again before you update Pūnaha.

Before you start

Choose an isolated knowledge database and a fictitious supported document. Confirm View, Create, Update, and Search separately where the journey needs them.

Follow the journey

1. List knowledge databases and select the intended name.
2. Read its current configuration.
3. Upload the smallest supported document using multipart/form-data.
4. Keep the document and ingestion job identifiers.
5. Read the ingestion job until it reaches a terminal state.
6. Read the document metadata and table of contents.
7. Search using a fictitious query.
8. Check that each result points to the intended source.

Handle failure

Correct unsupported, empty, encrypted, damaged, or oversized files before a new upload. If a provider or worker is unavailable, keep the request and job IDs, read current job state, and use bounded retry only when the operation says it is safe.

Clean up

Delete only the test document or database that the integration created. Check dependencies first. A delete request is not a reversible disable action.

Reference

Use the Knowledge and documents API reference and document format guide.

Processing destination and evidence

Use the customer contract for address availability and eligible processing servers. The job response includes target and processing information.

Recorded attempt evidence differs from a current configuration preview. Do not infer GPU execution from a saved accelerator setting.

Know which requests are public

Health, Swagger, the OpenAPI file, and some sign in requests do not need a session. Most product requests do.

Use the supported session

The current OpenAPI file lists two ways to send a Pūnaha session. A browser can use the secure punaha_session cookie. An API client can send the session token as a Bearer value.

Do not copy a person's password or browser cookie into an unattended program.

Plan unattended access

The current public API guide does not describe a separate credential for an outside application. Agree a safe sign in design before you use an unattended client in production.

Give exact access

Pūnaha checks the signed in identity, tenant, item, and action for each protected request. View, Search, Run, Create, Update, Work, Publish, and Delete are separate actions.

Handle an error

1. Save the HTTP status.
2. Save the safe error code and request ID.
3. Do not save the password, token, or secret key.
4. Reload the item before you repeat a request after a conflict.
5. Repeat a request only when it is safe to do so.

Keep versions together

Keep the API client, OpenAPI file, and Pūnaha version together. Test them again before an update.

Before you start

Use a published case type in a development tenant. Confirm the actor has the exact case actions needed by the journey.

Follow the journey

1. List case types and select the intended definition.
2. Read it and confirm the lifecycle state.
3. Create a case with the smallest valid fictitious information.
4. Keep the case identifier and request ID.
5. Read the case and available plan items.
6. Perform only an enabled and authorised plan item action.
7. Read the case again and confirm the resulting state.
8. Read any related files or events needed by the approved process.

Do not force lifecycle state

Use the specific transition or plan item action when one exists. Do not use a general update to bypass validation, required work, or an approval.

Handle conflict

Another actor or background action may change the case. Read current state, resolve the named conflict, and submit a deliberate new action.

Reference

Use the Cases and case types API reference for exact request and response fields.

Read the complete failure

1. Record the HTTP status.
2. Read the stable error.code.
3. Read safe values in error.details.
4. Keep the returned x-request-id.
5. Apply the operation's documented correction.

Know when not to retry

Validation, authentication, permission, licence, missing resource, and state conflict failures normally need a change before retry. Do not repeat a POST after an uncertain outcome until you have read the current resource or background operation state.

Use bounded retry for temporary failure

For an explicitly retryable dependency or capacity failure, use bounded exponential backoff and any documented Retry-After value. Stop after the approved limit and retain the request IDs.

Monitor background work

Keep the job, run, import, build, or activation identifier returned by the action. Poll the documented status operation or use its event stream. Treat waiting and terminal states differently.

Raise a support case safely

Provide the Product version, time, operation ID, status, stable error code, request ID, tenant identifier when safe, and background identifier. Do not attach credentials or customer content unless the approved support process requires it.

Reference

Each operation page lists causes, corrections, retryability, and partial work guidance. Shared error fields are in the Common HTTP models.

Registration is a separate gate

When the 720 powered on hour allowance is exhausted, ordinary API work and exports are denied. Repeated retries do not restore access. A System Owner must complete registration or renewal.

Keep this connection private

Workflow servers use private AI requests for model chat, knowledge search, and workflow text.

These requests do not appear in the public OpenAPI file.

Set up both services

1. Give Workflow the private AI address.
2. Create a long random service token.
3. Give the same token to the AI servers.
4. Set a request time limit.
5. Use HTTPS on the private network.

Limit the network

Only Workflow servers and trusted administrator networks should reach the private AI address. Use mTLS at the internal load balancer or service mesh in production.

The token is not enough by itself

The token proves that the request came from Workflow. Pūnaha still checks access to the model or knowledge database.

Operations

Operations

Operations

Operations

Operations

Operations

Operations

Use the same words across Pūnaha

This glossary gives each important word one preferred meaning. Follow the links when you need a fuller explanation or a task guide.

If a word is unclear

Search for the word and open the concept page before following a complex task. The task pages use these preferred meanings.

RC1 installation terms

What these concepts mean

A tenant is the area where one group of people, settings, and work belongs. A person joins the tenant as a member.

A group lets several people receive the same access. A membership role gives a tenant level starting set of access. A permission applies an exact Allow or Deny to an item and action.

Why they matter

Pūnaha checks the tenant, person, item, and action before protected work. Knowing a page address does not give access.

Actions are separate. View does not include Search, Run, Create, Update, Work, Publish, or Delete.

How access is combined

1. Start with the person's active membership role.
2. Add active access given directly to the person.
3. Add access from active local and external groups.
4. Apply the start and end dates.
5. Apply any matching Deny.

A matching Deny wins over an Allow. Removing one access record does not remove access supplied by another source.

Who manages them

Platform administrators create and manage tenants. Tenant member administrators manage people and groups. Tenant owners and appointed access administrators manage permissions within their authority.

Permission to manage access does not automatically give permission to use the item.

Related tasks

• Create and manage a tenant.
• Invite a person and give access.
• Manage access.
• Fix an access problem.

Return to the glossary.

What these concepts mean

A workflow is a connected set of steps. It receives information, performs work, and returns a result.

The draft is the editable copy. Publishing creates a numbered workflow version. A run is one use of a workflow version.

Why they matter

A published version keeps the behaviour used by a run. Editing the next draft does not change that older version.

The run keeps its version, state, events, approvals, and results so the work can be reviewed.

How they work together

1. A builder creates or changes the draft.
2. Pūnaha checks the draft.
3. The builder tests it with safe sample information.
4. Publishing creates a numbered version.
5. A person or service starts a run from an allowed version.
6. Pūnaha records the run as each step completes or fails.

Who manages them

Solution builders create and test drafts. A person with Publish access creates a version. A person or service with Run access starts a run.

Operators investigate waiting or failed work without changing the workflow design.

Related tasks

• Build, publish, and run a workflow.
• Choose workflow steps.
• Find and run workflows.
• Investigate a failed run.

Return to the glossary.

What these concepts mean

A case type defines one kind of work. It contains the information, roles, stages, tasks, requirements, and files used by that work.

A case is one item of work created from a published case type version.

Why they matter

The case type gives similar cases a shared structure. The case still responds to its own information and completed work.

A published case type version does not change. A new version does not move open cases by itself.

How they work together

1. A builder creates and checks a case type draft.
2. Publishing creates a numbered version.
3. A person opens a case from that version.
4. The case shows available work and requirements.
5. Case workers record outcomes and evidence.
6. Pūnaha adds important events to the case history.

Who manages them

Case solution builders manage case type drafts and versions. Case workers complete allowed work in individual cases. An authorised administrator can preview a move to a later version.

Related tasks

• Build a case type and work with a case.
• Build a case type.
• Work with cases.

Return to the glossary.

What a Connection is

A Connection stores the address, sign in method, network rules, and secret needed to reach email, an API, or a database.

A workflow refers to the Connection. It does not need to store the password or key in its own definition.

Why it matters

Connections keep shared system settings in one managed place. An administrator can test, disable, or update a Connection without copying its secret into each workflow.

What a test means

A successful test means the saved Connection worked at that time. It does not prove that every remote action is allowed or that the remote service will stay available.

A draft workflow should still test the exact operation it needs with safe sample information.

Who manages it

Tenant administrators manage the saved Connection. Solution builders choose an approved Connection in a draft. Access administrators decide who may view, change, test, or delete it.

Related tasks

• Configure and test a Connection.
• Use a Connection in a workflow.
• Investigate a failed Connection call.

Return to the glossary.

What these concepts mean

A model performs an enabled AI task. Response generation creates text. An embedding model turns text into numeric values that can be compared by meaning.

A knowledge database holds processed documents and searchable passages. Access and API pages may call the same resource a vector database.

Why they matter

The embedding model used to store a passage must match the way the database searches it. Changing that choice requires the stored vectors to be created again.

A search result returns stored passages. A workflow or person must still check whether a passage supports the answer they need.

How they work together

1. An administrator prepares and enables an embedding model.
2. A knowledge owner creates a database with that model.
3. Pūnaha reads an uploaded document.
4. It splits the readable text into passages.
5. The embedding model represents each passage.
6. A search compares the question with the stored passages.

Who manages them

AI administrators manage model Connections, models, deployments, and the local runtime. Knowledge owners manage knowledge databases and documents. Access administrators control each allowed item and action.

Related tasks

• Prepare a model and knowledge database.
• Upload and search knowledge.
• Run local AI models.

Return to the glossary.

What these concepts mean

An operational log records service and request events. Use it to understand what happened while work ran or failed.

An audit record describes an important security, access, or administration event. Use it to understand who changed an important item and whether the action succeeded.

Why they matter

The two records answer different questions. A log may show why a request failed. An audit record may show the earlier access or setting change that affected it.

Request, run, job, case, and item IDs can connect related records.

How they work together

1. Start with the person, tenant, time, message, and best available ID.
2. Find the work state in Operations.
3. Read the matching log events in time order.
4. Check audit history when an administration change may be involved.
5. Compare the first failure with the change time.

Who manages them

Operators search operational logs. Auditors and authorised administrators review audit records. Access rules decide who may view each record type.

Both record types may contain personal or security information. Protect exports under your organisation's rules.

Related tasks

• Check operations, logs, and audit records.
• Use logs and audit records.
• Use the Operations pages.

Return to the glossary.

Main commands

punaha serve [--services=all|control|workflow|ai|frontend]
punaha migrate
punaha setup-code [--valid-for=15m]
punaha bootstrap-admin --email admin@example.com --password-stdin
punaha service install|uninstall|start|stop|restart|status|run
punaha version

Start services

Use serve to start Pūnaha. Use --services to choose which services run on that computer.

Update databases

Run migrate before you start an updated service.

Recover setup

Run setup-code on the server if a browser setup session is stuck. The command ends the old session and gives you a short lived code.

Check the service

After a start or restart, run service status. Then check the Ready health address.

Registration and packaged services

Use Registration & licence for RC1 activation and renewal. Installer acceptance is separate from registration.

Use the packaged service lifecycle and platform upgrade instructions for installed systems.

Development ports

Production web address

Configure each public frontend and API origin explicitly, normally using HTTPS on port 443. Keep databases and private cluster listeners off the public network.

Which service owns each area

• Control: Sign in, tenants, people, settings, access, audit, licences, and logs.
• Workflow: Workflows, decisions, cases, and their Connections.
• AI: Knowledge, models, chat, and embeddings.

Health addresses

Use /health/live to check that the program is running. Use /health/ready to check that it can receive work.

Choose the problem

• Sign in, invitations, and access
• Models, uploads, and knowledge search
• Workflows and Connections
• Service readiness and storage
• Logs, backups, and restores

Keep the first evidence

Write down what the person tried to do, the tenant, the time, the exact message, and any request, run, job, case, or item ID.

Do not collect passwords, sign in codes, tokens, private keys, Connection secrets, or copies of customer information that are not needed.

Change one thing at a time

1. Read the visible message.
2. Check the item in the product.
3. Use the matching guide.
4. Change only the most likely cause.
5. Check the result before making another change.

Start with access when an area is missing

A missing area can be a correct restricted state. Do not treat it as a broken page until Check access shows that the exact action should be allowed.

Only registration is available

Read Fix registration and renewal problems when normal Product areas and exports are blocked.

What you see

• Only sign in and registration are available.
• The powered hour allowance is exhausted or cannot be verified.
• An activation file is rejected.
• The request is waiting for Support approval.

What it means

Normal work needs an active term or a remaining verified allowance. A submitted request has not yet activated the installation. Restricted access retains your data without ordinary access or export.

Likely causes

The allowance may be exhausted. The activation may belong to another request or installation. The hardware clock or protected state may be unavailable or inconsistent.

Safe checks

1. Sign in as System Owner and open Registration & licence.
2. Read the request reference, term, allowance, and current next action.
3. Check the Product's configured Support connection or use the offline exchange.
4. Check that the returned activation belongs to the current request.
5. For a clock error, have the operator check TPM health and the matching protected state.

Solutions

Complete registration or renewal and apply a verified active term. Correct a computer date error before generating a new time limited request.

Restore the corresponding protected Control record and node state together when recovering a backup. Do not delete counters, clear the TPM, or restore only one side.

A full VM snapshot including its vTPM and protected state needs independent operational controls. Local software cannot promise detection of every complete machine rollback.

What to collect

Record the Product version, request reference, status, safe error code, and time. Do not collect private keys, activation secrets, passwords, or unfiltered database contents.

Next step

Read Offline registration and renewal or Registration timing.

What you see

• Pūnaha asks you to sign in again.
• An invitation says it is used, revoked, expired, invalid, or for another account.
• A menu or button is missing.
• The page says This area is not assigned to you or returns Forbidden.

What it means

A sign in session may have ended. An invitation has one named account, sign in method, state, and expiry time.

A missing area or Forbidden result means the current person does not have the exact action. If no access is intended, this is the correct restricted state.

Likely causes

• The session expired.
• The invitation was already accepted, revoked, or reached its expiry time.
• The person used a different email account or identity provider.
• The person has View but not Search, Run, Create, Update, Work, Publish, or Delete.
• An assignment has not started, has expired, or is blocked by a matching Deny.
• A local or external group is inactive or does not include the person.

Safe checks

1. Read the exact message and record the time.
2. For sign in, open the normal Pūnaha address and try once more.
3. For an invitation, ask an administrator to check its state, email address, sign in Connection, and expiry time.
4. For access, select the person in Permissions.
5. Use Check access for one named item and the exact failed action.
6. Read every direct, role, and group source, including any Deny.

Solutions

• Sign in again when the session expired.
• Use the account named in a valid invitation.
• Send a new invitation only after the old invitation state or account mismatch is confirmed.
• Add only the missing action when the person should have it.
• Correct an inactive group, date, or assignment only when it is wrong.
• Make no change when the restricted state is intended.

A saved page address never bypasses access.

What to collect

Collect the tenant name, person, invitation state, item type, named item, action, time, Check access explanation, and request ID.

Do not collect a password, sign in code, token, identity provider secret, or customer document.

Related guides

Read Invite a person and give access and Fix an access problem.

Organisation sign in or registration restriction

Check public origins and OIDC callbacks when sign in returns to the wrong address.

A registration restriction is different from a missing tenant permission. Read registration recovery when only that area remains available.

What you see

• No approved model is available for the required work.
• A model file upload stops or the local runtime is unavailable.
• A document is rejected or stays failed in Operations.
• Knowledge search returns no passage or the wrong passage.

What it means

The required model may not be ready or enabled. A document must pass the file policy, be readable, and finish processing before its passages can be searched.

Search also needs the exact Search action. View access is not enough.

Likely causes

• The model Connection, deployment, local runtime, or model file is not ready.
• The document type or size is not allowed.
• The file is empty, encrypted, damaged, or contains no readable text.
• Document processing is paused, waiting, or failed.
• The question does not use words or meaning found in the stored passage.
• The person lacks Search access to this knowledge database.

Safe checks

1. Check the model state and the work it is enabled to perform.
2. Test the model Connection without copying its secret.
3. Check the current upload policy before trying the file again.
4. Open the document and read its processing stage and message.
5. Find the matching job in Tenant operations.
6. Use Check access for Search on the named knowledge database.
7. Search for one fact that clearly appears in a finished document.

Solutions

• Enable an approved ready model for the required work.
• For an interrupted GGUF upload, try again or place the approved file in the configured model folder and refresh.
• Use a supported file that is within the shown limits and contains readable text.
• Resume document processing when an authorised administrator paused it.
• Correct the identified processing cause before retrying the job.
• Add Search access only when the person should search the database.
• Improve the source or search question when the stored passage does not contain the needed information.

What to collect

Collect the tenant, model or database name, safe file name and type, file size, processing stage, time, job ID, request ID, and visible message.

Do not collect model credentials, provider keys, customer document contents, or a private model file.

Related guides

Read Prepare a model and knowledge database, Upload and search knowledge, and Run local AI models.

Processing is waiting or stopped

Read the document stage, current owner, capacity wait, and original error. Use document controls and model scheduling.

What you see

• The workflow draft says it needs attention or cannot be published.
• A run stays waiting or ends as failed.
• A Connection test fails.
• A Connection test passes but the workflow operation fails.

What it means

A draft must pass its checks before it can be published. A run keeps the exact workflow version and events used for that attempt.

A Connection test proves only that the saved Connection worked for its test at that time. The workflow may need another remote action or different information.

Likely causes

• A required step, input, link, or setting is missing from the draft.
• The run is waiting for work, approval, a service, or a safe retry.
• The remote address, port, sign in method, secure connection setting, or network rule is wrong.
• The remote account does not allow the exact operation.
• The Connection was changed after the workflow version was published.
• The person or Workflow service lacks the exact Run or resource action.

Safe checks

1. Run Check readiness on the draft and read every issue.
2. Confirm the run uses the expected published version.
3. Find the run in Operations and record its state and run ID.
4. Read the first matching failure in Operational logs.
5. Test the saved Connection once.
6. Check its address, secure connection choice, and allowed network without showing its secret.
7. Use Check access for the exact workflow or remote resource action.

Solutions

• Correct each reported draft issue, then check the draft again.
• Publish a new version only after a safe draft test passes.
• Correct the identified Connection or network setting, then test once more.
• Ask the remote system owner for the required operation when the account is too limited.
• Retry a run only when the operation is safe to repeat.
• Give the smallest required access when Check access confirms it is missing.

What to collect

Collect the tenant, workflow name and version, run ID, step name, Connection name, time, request ID, state, and visible message.

Do not collect a password, token, private key, Connection secret, request body, or customer result unless a separate secure review needs it.

Related guides

Read Build, publish, and run a workflow, Manage Connections, and Investigate a problem.

What you see

• /health/live succeeds but /health/ready does not.
• A service does not appear as ready in System operations.
• Documents, knowledge indexes, or logs are unavailable.
• Old knowledge seems missing after a storage destination changed.

What it means

Live means the program is running. Ready means it can receive its normal work.

Changing a storage destination does not move old data. The old data remains at its earlier destination until an approved move or rebuild is complete.

Likely causes

• A required Control, Workflow, or AI database is unavailable or needs an update.
• A Workflow server has no local AI service and cannot reach its private AI address.
• A service setting, private network route, or internal authentication value does not match.
• The configured storage path, bucket, container, permission, or key is wrong.
• Several servers use local storage instead of one approved shared destination.
• The storage setting changed before old data was moved or rebuilt.

Safe checks

1. Check Live and Ready separately on the affected service.
2. Read the service state in System operations.
3. Check the first readiness message in the service logs.
4. Confirm the expected service role and required database are reachable.
5. For Workflow, confirm that local AI is present or the approved private AI address is set.
6. Compare the configured storage destination with the approved design.
7. Confirm that every server which needs shared data uses the same durable destination.

Solutions

• Restore the required database, service, or private route before returning the server to traffic.
• Run an approved database update once before starting the updated service group.
• Correct only the identified storage setting or permission.
• Keep an unready server out of the load balancer.
• Move existing data or rebuild knowledge from approved source documents before switching storage.
• Do not silently use local storage when shared storage is required.

What to collect

Collect the product version, service role, server name, Live and Ready results, time, safe destination name, database version, request ID, and visible message.

Do not collect database passwords, storage keys, internal service tokens, private network details that are not needed, or customer files.

Related guides

Read Check service health, Run Pūnaha on several servers, and Plan storage and backups.

What you see

• A log or audit search returns no matching record.
• A backup is missing one database or file store.
• A restored system starts but workflows, cases, knowledge, models, or records are missing.
• One restored service is not ready.

What it means

Log and audit searches depend on the tenant, time, filters, destination, and access. A complete Pūnaha recovery needs related databases and file data from one release checkpoint.

A process starting does not prove that its restored data is complete or consistent.

Likely causes

• The search uses the wrong tenant, time range, time zone, ID, or record type.
• The person lacks access to the record.
• The log destination changed or was unavailable.
• Control, Workflow, and AI databases were backed up at different points.
• Document, model, knowledge, runtime, or log files were left out.
• The product or database versions do not match the recorded checkpoint.

Safe checks

1. Confirm whether you need an operational log or an audit record.
2. Use the correct tenant and a short time range around the event.
3. Search with one request, run, job, case, or item ID.
4. Check access and the configured log destination.
5. Compare the backup contents with the approved backup list.
6. Confirm the recorded product version and all three database versions.
7. Test the restore on a separate system.
8. Check sign in, access, workflows, cases, knowledge, models, audit, and service readiness.

Solutions

• Correct the search filters or access when the record exists.
• Restore the approved log destination when it is unavailable.
• Create a new complete checkpoint when the backup is inconsistent.
• Repeat the test restore from a verified complete checkpoint.
• Follow the approved recovery process when a required store is missing.
• Do not place an unverified restored system into production traffic.

What to collect

Collect the product version, database versions, backup time, restore time, store names, service states, safe record counts, failed check, request ID, and visible message.

Do not collect database dumps, passwords, keys, tokens, customer files, or exported logs in an ordinary support message.

Related guides

Read Use logs and audit records, Plan storage and backups, and Investigate a problem.

Open the Environment group

The platform Configuration page shows safe information about the current environment.

Server and ports

PUNAHA_ENV sets the environment. PUNAHA_SERVICES chooses services. The API and frontend host and port settings choose their addresses.

Data and server name

PUNAHA_DATA_DIRECTORY chooses the data folder. PUNAHA_SERVER_ID and PUNAHA_SERVER_NAME identify the server.

Sign in and licence

The setup, sign in, encryption, audit, licence file, and public key settings protect access to the installation.

Databases

Control, Workflow, and AI each have settings for the server, port, database name, normal account, update account, TLS, and connection count.

AI settings

Other settings control the private AI address, LanceDB, llama.cpp, model folders, processor, context size, batch size, threads, and GPU layers.

Keep passwords, tokens, and encryption keys out of source control.

Installed database and identity state

PUNAHA_DATABASE_PROVIDER supplies a provider choice before setup. The protected installation state becomes authoritative after setup.

Control, Workflow, and AI use PUNAHA_CONTROL_DB_*, PUNAHA_WORKFLOW_DB_*, and PUNAHA_AI_DB_*. Changing them does not provide a cross provider migration.

The 720 powered on hour allowance is not an environment setting. Read registration and renewal.

Supported file types

.txt .log .md .markdown .csv .json .html .htm .xml .yaml .yml .pdf .msg .eml .rtf .epub .odt .ods .odp .docx .docm .dotx .dotm .xlsx .xlsm .xltx .xltm .pptx .pptm .ppsx .ppsm .potx .potm

Upload limits

You can choose up to 20 files in one upload. One file can be up to 2 GB. A tenant may have a lower limit.

Checks before upload

Pūnaha rejects files that are empty, damaged, encrypted, or not supported. It also checks compressed file packages for unsafe paths and very large content.

Readable text

A file with only images may not have text that Pūnaha can search. Outlook MSG and EML files can include supported attachments.

Remove encryption before you upload a PDF, email, OpenDocument file, or Microsoft Office file.

Chat attachments use separate limits

Chat accepts TXT, MD, CSV, JSON, PDF, and DOCX only. Up to three files are allowed, each up to 1 MiB, with a combined 2 MiB limit.

Combined extracted attachment text is limited to 100,000 UTF-16 code units. The complete message with document context must fit 200,000 units. Oversized context is rejected, not silently truncated.

Read Use Chat for handling and retention. The larger Knowledge limits do not apply to Chat.

Start with the question

• How sign in and access work
• How tenant separation works
• Where data is stored and when it moves
• What audit records cover and how to handle sensitive information
• How to configure secrets safely

Know the scope

These pages describe controls found in the current product source. They are not a security certification. Your organisation still needs its own risk review, identity rules, network controls, backup controls, and response process.

Keep three services separate

Pūnaha product data belongs to the customer installation or its configured providers. The public documentation site is separate. A support message is also separate.

Do not copy customer data, passwords, tokens, or private keys into documentation search or an ordinary support message.

Use the smallest access

Give only the named items and actions needed for the work. Review access and audit records. Remove access when the need ends.

Registration information and receipts

Registration sends the declared identity and installation metadata through the configured Support flow. Optional email sharing is separate from licence acceptance.

Retain the accepted document versions and hashes. Read the exact licence and privacy notice supplied with your RC1 package.

Authentication proves an identity

A person signs in and receives a session. Pūnaha uses the trusted identity and selected tenant for later requests.

RC1 includes local sign in with MFA and OpenID Connect organisation sign in. The first System Owner must complete the selected verification. External callbacks must match the configured public frontend and API mapping.

Access decides what the identity can do

Membership roles provide a starting set of tenant access. Direct assignments and active groups can add access. An exact matching Deny overrides an Allow.

View, Search, Run, Create, Update, Work, Publish, and Delete are separate decisions.

The service checks every protected request

The menu hides areas that are not assigned. This helps the person find their work, but it is not the security boundary.

The service checks the tenant, item, and action again. A saved address cannot bypass this check.

Service identities also need access

Workflow uses a fixed service identity when it calls private AI operations. Internal authentication alone does not give resource access. The service identity also needs the matching Control permission.

Use the current limitation honestly

Configure and test the intended sign in method. Read Public addresses and organisation sign in for exact callback mappings.

Related tasks

Read Manage access, Review access, and Fix sign in, invitation, and access problems.

Registration gate

After the powered hour allowance is exhausted, successful sign in only permits the functions needed to restore registration. It does not reopen tenant data or ordinary administration.

Tenant separation is enforced by the service

Tenant records carry a tenant identity. Product requests and database queries use the selected tenant identity with the named resource.

A missing, old, or different tenant resource identity fails closed during access checks.

Tenants are not separate physical databases

Pūnaha has separate Control, Workflow, and AI databases by service purpose. Each of those databases can hold records for more than one tenant.

Tenant separation therefore depends on server checks and tenant scoped data access. Do not claim that every tenant has a separate database.

Access remains tenant scoped

A normal tenant member receives access inside the selected tenant. A resource grant refers to an item in that tenant.

Platform administration has wider authority by design. Limit it to approved people and review its audit records.

Child information is limited

Access to a child item can expose the minimum parent name needed to find it. It does not give access to sibling items or the parent management page.

Check separation safely

1. Use approved test tenants and test accounts.
2. Confirm an allowed item appears in its tenant.
3. Confirm a different tenant item does not appear.
4. Try the direct address and confirm the service still blocks it.
5. Keep the request and audit IDs as evidence.

Never use real customer data in a separation test unless the approved test plan requires it.

Related tasks

Read Manage tenants, Tenants, people, and access, and Understand administration responsibilities.

Start with the main data stores

Storage choice controls location

The installation can use filesystem, S3 compatible, and Azure Blob storage. Confirm the active adapter and service identity for each data type.

RC1 implements S3 and Azure Blob document delivery. GGUF model weights still need a filesystem location. Verify read and write access on every intended node.

Data moves when an approved action sends it

• An external model provider receives the content included in its model request.
• An email, API, or database Connection sends the fields used by that workflow step.
• A cloud storage adapter sends stored files or logs to its configured destination when that adapter is available.
• An administrator can export authorised audit or access review records while normal Product access is available. Registration restriction blocks ordinary exports.

Local processing can reduce movement

The embedded model runtime and built in document extraction run in the Pūnaha installation. Workflow protection checks also run in the product rather than sending content to a separate moderation service.

Local processing does not make all work local when a workflow uses an external model or Connection.

Documentation and support are separate

The documentation site does not store Pūnaha tenant records. Its local search reads the published documentation index.

Customer data is not needed for normal documentation search. Share only approved, reduced evidence through your organisation's support process.

Review each movement

1. Name the data and its owner.
2. Name the source and destination.
3. Confirm the approved provider, region, and agreement.
4. Reduce the fields to what the action needs.
5. Check access, encryption, retention, logs, and deletion.
6. Test with safe sample information.

Related tasks

Read Manage settings, Manage Connections, and Plan storage and backups.

Chat and registration information

Chat stores extracted attachment text and metadata with its run. It does not store the original binary as a Knowledge document.

The configured registration flow sends declared installation metadata to Support. Review the supplied privacy notice and keep optional sharing choices separate.

Use the right record

Audit records show important security, access, and administration events. Operational logs explain service and request behaviour.

Neither record proves every business decision by itself. Use the workflow run or case history when the product work is the subject.

What an audit record can show

An available audit record can include the person or service, tenant, action, resource, result, time, and request ID. Coverage depends on the event recorded by the current build.

Do not claim that an event is audited until a safe test or current product evidence confirms it.

Records can be sensitive

Logs and audit records can contain names, identifiers, addresses, paths, error details, and information about access or system changes.

Limit who can view and export them. Store exports under your organisation's retention and protection rules.

Collect the minimum

1. Use a short time range.
2. Use one tenant and the best available ID.
3. Keep only the records needed for the question.
4. Remove unrelated personal or customer information before sharing when allowed.
5. Use the approved secure support route.

Never add secrets to evidence

Do not put passwords, sign in codes, tokens, private keys, Connection secrets, provider keys, or database credentials into a note, screenshot, export, or support message.

If a secret may have been exposed, stop using it and follow the approved rotation and response process.

Related tasks

Read Use logs and audit records, Investigate a problem, and Operational logs and audit records.

Five parts of access

How Pūnaha decides

Pūnaha combines access from roles, direct assignments, and groups. A matching Deny wins over an Allow.

The API checks the exact item and action for every request.

Administration is separate

Permission to manage access does not give permission to use the item. Permission to manage people is also separate.

Check one question

Use Check access for one person, item, and action. Use Effective access when you need to see all sources together.

Know what is secret

Passwords, provider keys, database credentials, private keys, internal service tokens, sign in codes, and session tokens are secrets.

Server addresses, tenant names, and resource IDs may also need protection under your organisation's rules even when they are not credentials.

Store secrets only in approved fields

Use the secret field for a Connection or storage destination. Use the approved server secret store for service configuration.

The current product encrypts saved Connection and storage credentials before keeping them in the database. Settings responses do not return stored cloud credentials.

Use a limited account

Give the remote account only the network and data actions needed by the Connection. Use a separate account for each environment when possible.

Do not use a personal owner account for normal service work.

Test without exposing the value

1. Confirm the destination and sign in method.
2. Enter the secret directly into the approved field.
3. Save and test the Connection.
4. Read the result without copying the secret.
5. Test the exact workflow action with safe sample information.

Change and rotate safely

1. Name the affected Connections and services.
2. Create the new secret at its source.
3. Update the approved product setting.
4. Test the new value.
5. Remove the old value at its source.
6. Check logs and audit records for unexpected use.

If a secret is exposed

Do not paste it into a message or ask another person to confirm it. Stop or limit its use, rotate it at the source, update the product, and follow your response process.

Related tasks

Read Manage Connections, Manage settings, and Fix workflow and Connection problems.

Registration and licence

Future renewal pricing is undecided and may include a charge based on user group demand and actual maintenance and development costs. Proposed terms and prices will be disclosed in advance. Paid renewal requires explicit acceptance. There is no automatic charge or obligation to renew. Issued terms and prior accepted commitments are honoured. Optional support is separate.

Renew or export before the 720 powered on hour cutoff. Ordinary processing, administration, customer data access, and exports stop after that cutoff. Data is retained. This allowance is not 30 calendar days.

The current issued 12 month term costs US$0 from the signed issue date. Initial registration and renewal after term expiry each have 720 powered on hours of normal use.

Powered off time does not count. Ordinary restarts and date changes do not reset the allowance. It is not customer editable.

Processing defaults

Upload limits

A GGUF model can be up to 32 GB. Knowledge accepts up to 20 files per upload and up to 2 GB per document before a lower tenant limit.

Chat accepts up to three supported files per message. Each file is limited to 1 MiB and the combined originals to 2 MiB.

Storage and changes

Use the installed Local, Security, and Cluster roots. Files prepared in parallel requires a restart. Other processing controls have their own application rules.

Read model scheduling, shared storage, and registration timing.

Choose the version that matches the product

Check the release identity

A released version page shows the exact product version, release date, and trusted product tag or commit. The documentation snapshot also has a content hash.

A local development snapshot is not an official supported release unless the approved product release record says it is.

Read all release information

• Release notes explain approved additions, changes, fixes, and breaking changes.
• Known problems explain verified symptoms, impact, and safe workarounds.
• Supported versions come from the approved support policy.
• Deprecation notices explain an approved future removal and replacement.
• Upgrade guidance gives a tested path between exact versions.

If one of these pages is absent, do not guess its answer.

Do not use unverified upgrade steps

Upgrade steps are published only after the product process is stable. The exact source and target path must pass backup, restore, upgrade, result, and rollback checks.

Until then, keep using the approved process for the installed product version.

Older releases do not change

A released page is an immutable snapshot. Its screenshots, examples, API contract, and offline download remain tied to that release.

A later correction belongs in a new, clearly identified documentation release. The original snapshot remains available for evidence.

Open help from your installation

Help for this page uses the version stamped into the installed Product. A released build opens its exact documentation version. Local development builds can open Next.

The guide warns when the Product revision supplied by Help differs from its reviewed revision. Check that warning before following instructions.

If matching documentation is unavailable, use the matching offline download or contact your installation owner. Do not substitute newer instructions.

Check build details

Each guide shows its Product revision. A frozen version also records the Product build, documentation revision, and hashes for its content and downloads.

Use the build details and matching API contract linked from that version. Feedback is recorded with the selected documentation version and page.

Use the version picker

Choose the version near the page title. Search results stay inside that version. Check the version again before following an administration, API, or upgrade instruction.

For release authors

Complete the release notes, known problems, support, deprecation, upgrade, and review templates. Remove every instruction and missing value before approval.

Know what can become out of date

A product change can affect a task, result, screenshot, command, limit, or link. It can also change the words used in the interface.

Every Next page lists the product files used as evidence. The documentation evidence record stores a fingerprint for those files.

Use the automatic review signal

Run the product drift check after the product changes. It compares the current product files with the evidence from the last reviewed documentation update.

A changed fingerprint marks the linked pages for review. It does not rewrite, approve, release, or publish a page.

Review a marked page

1. Read the changed product source and its tests.
2. Follow the task in a safe current build.
3. Update only statements that the evidence supports.
4. Check every expected result and safe recovery step.
5. Keep the existing page address when its purpose has not changed.
6. Record the new verification date.

Review screenshots

1. Compare each screenshot with the current screen at the same step.
2. Take a new screenshot if controls, wording, order, or results changed.
3. Use safe example data with no secrets or customer information.
4. Crop the image so the action and result are easy to see.
5. Write image text that explains the useful information.

A screenshot can remain when the screen and the instruction still match.

Run the documentation checks

The checks cover page details, simple English, image text, headings, internal links, important search words, accessibility support, and package requirements.

They also build the site, search index, and offline files. A failed check must be fixed or recorded as a release blocker.

Complete the human review

Use the accessibility review checklist with a keyboard, small screen, zoom, and a screen reader. Read the changed page as a new user would.

Automation cannot confirm that a screenshot is still true or that an instruction is easy to follow.

Release only reviewed information

Approve updated Next pages after the facts, images, links, search, and accessibility review pass. Follow the version and release guide before creating a release snapshot.

Use the troubleshooting guides to check that recovery advice remains safe.

What we checked

The editable guides describe 0.1 RC1 from Product source reviewed on 6 October 2026. Read the exact source revision and acceptance boundaries.

What is included

Coverage includes installation, database providers, first setup, registration and renewal, trusted nodes, public addresses, storage, AI, documents, Chat, workflows, cases, solution packages, and the customer API.

How to read the evidence

Source review and automated documentation checks do not establish installed platform acceptance. Earlier screenshots are dated illustrations, not proof of the RC1 interface.

What remains separate

• The Product and documentation remain unpublished.
• Package signing evidence does not prove every installation and recovery journey.
• Database and operating system support require the exact package's qualification record.
• No full BPMN, DMN, or CMMN certification is claimed.
• Customer information and private implementation evidence are not documentation content.

Future changes

API generation refreshes the customer reference. Editorial review separately updates guides and their evidence. Historical release snapshots remain unchanged.