What is SpruceTip
SpruceTip is a web-based expert system that can be added to any WordPress site. It transforms existing site content, uploaded files, and other knowledge sources into custom-engineered intelligent workflows. The dynamic user interface helps automate administrative decision-making and facilitates exchanges with site users to solicit and infer information, tailoring every exchange to the user.
Getting Started
Go to SpruceTip → Settings and save your Gemini API key. The other settings appear once it’s saved. Then add your SpruceTip token and choose a Default model. Workflows use this model when they don’t have an assistant.
(Optional) Set your brand colours in SpruceTip → Questionnaire Styles.
(Optional) Create an assistant if your workflows should draw on your site content or files.
Create a workflow in SpruceTip → Workflows → Add New.
Preview it, then save it.
Add it to a page.
Creating a Workflow
A workflow is an AI-powered questionnaire. As people answer, it chooses which questions to show next. It can also fill in answers for them, using their earlier answers, your knowledge base and Gemini's reasoning.
To create one, go to SpruceTip → Workflows and click Add New. You'll be asked to choose a starting point: a template or a blank workflow. Nothing is saved until you click Save.

Templates
Each template is a complete, working workflow. Use it as is, or change anything you like.
Contact form: asks for a name, email and message. Gemini routes each message to Support, Sales or General, then asks the right follow-up questions.
Sales lead form: asks about the contact, company, budget and timeline. Promising leads get an AI project outline; others are invited to stay in touch.
Job application: asks for contact details, a CV upload and experience. Technical roles get an extra skills step. Every application gets a candidate summary.
Enrolment application: asks for the applicant’s details, program choice and goals. Applicants who aren’t sure which program fits get a guidance step. Every application gets a summary.
After choosing a template, check Workflow settings (especially the administrator email), preview it and save it. Then run it once on your site to check the Gemini steps.
Blank workflow starts from scratch. You fill in the workflow settings first, then click Continue to chains.
Workflow Settings
To change these settings later, click the gear next to the workflow name.
Description: for your own reference only. It isn’t shared with Gemini.
Assistant: the assistant that runs this workflow. With no assistant, the default Gemini model is used.
Enable user email: emails people a copy of their answers. The workflow needs an Email address interaction for this.
Resume unfinished entries: emails people who leave before finishing a link back to the form. Choose when it’s sent (after 1 hour, 2 hours, 1 day or 3 days) and how long the link works (1, 3 or 7 days).
Enable administrator email: emails a copy of each completed entry to an administrator. If the address is left blank, it goes to the site’s admin email.
Fullscreen button: lets people open the form in fullscreen.
Progress sidebar: shows the chapters and steps beside the form. Turn it off for a single-column form.
Sidebar button: lets people hide and show the progress sidebar.
Workflow id: the tag next to the workflow name. It’s used in the shortcode and must be unique on your site. You can edit it until the first save; after that it’s locked.

Creating an Assistant
An assistant customizes the AI used to run a workflow. Its instructions are guidelines Gemini follows with every request in workflows that use it.
To create one, go to SpruceTip → Assistants and click Add New. Then choose it under Assistant in a workflow’s settings.
Knowledge Base
Posts and pages: choose the published posts and pages the assistant can use as reference. Click Add posts and search for them.
Files: upload reference files. Uploaded files stay private to SpruceTip and can’t be reached through the website or the media library.
Adding a page doesn’t add the pages or files it links to. Add those separately.
Creating a Chain
A chain is a group of interactions, split across one or more form pages, that people complete as one stage of the workflow, like “About you” or “Project details”.
In the workflow builder, the Chains tab lists every chain. Click Add chain to add one, and drag chains to reorder them.
The root chain is always first. Every workflow starts there, so it can’t be moved or deleted.
System instructions (optional): rules for how Gemini fills in this chain’s interactions and reads the answers it receives. Leave them blank to use the default behaviour. The root chain has no instructions because it starts automatically.
Form pages: everything on a page is shown at once, and people move between pages with Back and Next. Each page has a title and a Page layout of One column or Two columns. Drag pages to reorder them.
Output message: the closing message shown when someone finishes the chain. It’s only used by chains with no branches, where the workflow ends.
Duplicate chain copies the chain with its pages, interactions and branches. Delete chain also deletes its interactions and any branches that point to it.
The Workflow tree tab shows the whole workflow as a map: which chain leads where, and when. Chains that no branch leads to are listed under Not reachable from root.

Branches
Branches decide where people go after a chain. Gemini reads each branch’s condition, looks at the answers and picks the best match.
No branches: the workflow ends and people see the chain’s output message.
One branch: it’s an Always branch, so everyone continues to that chain.
Two or more branches: each one needs a When condition describing when Gemini should take it.
Conditions don’t need to be logic rules like “if answer = yes”. Describe the situation in plain language, for example: “The person wants help with an existing order or account.”
A chain can’t branch to itself or to the same chain twice. Combine those conditions into one branch instead.
A branch can’t lead back to an earlier chain, so a workflow can never loop.
Different chains can branch to the same chain, so several paths can share a common step instead of repeating it. The workflow is a Directed Acyclic Graph (DAG).


Creating an Interaction
An interaction is a single question, or a piece of text shown to the user. Each interaction belongs to one chain.
To add one to a form page, click + Add interaction and choose from:
Add existing: reuse an interaction from this workflow. If it belongs to another chain, it’s added as a copy with its own answers.
Premade: ready-made Name, Email, Telephone, Website and Address questions.
Create new: give it a title and choose a type.
You can drag interactions between pages.

Types
Text input: a single-line answer
Paragraph: a multi-line answer
Email address: a single-line answer that must be a valid email address
Select dropdown: choose one option from a list
Radio buttons: choose one option
Checkboxes: choose any number of options
Number stepper: choose a number
File upload: upload a file (PDF only, up to 20 MB)
Text output: shows text and has no answer. It can show fixed text, or text Gemini writes for each person
Interaction Settings
Click Settings on an interaction to change it.
Display title: the question people see.
Display description: helper text shown under the title.
Placeholder / Default value: hint text, or a starting answer.
Options: the choices for dropdowns, radio buttons and checkboxes.
Input required: people can’t continue until it’s answered.
Use Gemini: for a question, Gemini fills in an answer based on what the person has said so far, and they can review and change it. For a Text output, Gemini writes the text for that person. If Gemini has nothing to add, the default value is used, or the field is left empty. This option isn’t available in the root chain, because there are no earlier answers yet.
Show in report: includes the answer in the PDF report and emails.

Email Notifications
SpruceTip sends emails with wp_mail(), WordPress’s built-in mail function. If emails aren’t arriving, check your site’s mail setup.
User email: if Enable user email is on, people receive a copy of their answers when they finish the workflow. The workflow needs an Email address interaction for this.
Administrator email: if Enable administrator email is on, an administrator receives the same copy plus internal details: the chain instructions, why Gemini chose each branch, and links to uploaded files. It goes to the address set in the workflow’s settings, or to the site’s admin email if left blank.
Resume email: if Resume unfinished entries is on, people who leave before finishing get one email with a link back to the form. See Error Handling below.
Previewing and Saving
Click Preview to go through the form as it is now, even before saving. Nothing is saved, Gemini doesn’t run, no emails are sent, and Next works without answers.
In the preview, Jump to goes straight to any page and Restart starts it over. At the end of a chain with branches, you choose which branch to preview. You can also switch between Desktop, Tablet and Phone sizes.

Saving
Click Save. The status shows Unsaved changes until you save, then Saved just now.
Saving syncs the workflow with SpruceTip automatically. A banner at the top of the screen shows the sync’s progress and result.
If a sync fails, click Sync to try again. It re-syncs every chain, interaction and the assistant.
If something in the workflow needs fixing, Save stops and the status explains why. For example, an interaction can’t be in two chains.
After the first save, you can also use Copy shortcode to add the workflow to a page, and Clone to copy the whole workflow.
Running a Workflow
Once a workflow is saved, add it to a page on your site so people can use it.
Adding a Workflow to a Page
Copy the workflow’s shortcode. Use Copy shortcode in the builder, or the Copy shortcode link in the Workflows list. It looks like this: [sj_questionnaire workflow="contact-form"]
Paste it into any page or post. To limit the width, add max_width, for example: [sj_questionnaire workflow="contact-form" max_width="900px"]
In the classic editor you can instead click Add Questionnaire above the editor, choose the workflow and click Insert questionnaire.
Publish the page. The Used on column in the Workflows list shows which pages each workflow appears on.
User Flow
When someone opens the page, the workflow starts at the root chain’s first page.
They go through the chain’s pages, using Back and Next.
When they finish a chain that has branches, SpruceTip does two things: it chooses the next chain based on the branch conditions, then fills in that chain’s interactions that use Gemini.
The next chain opens with those answers filled in. People can review and change them, and read any text Gemini wrote for them.
This repeats until they finish a chain with no branches. Then they see its output message, and the entry is complete.

Error Handling
Progress Auto-Save
Answers are saved as people go, and each entry is tracked by the person’s email address. The workflow needs an Email address interaction for this.
If Resume unfinished entries is on and someone leaves before finishing, they get one email with a link back to the form. It’s sent after the delay set in the workflow’s settings, 2 hours by default.
The link takes them back to the last chain they reached. It stops working when the “Link works for” period ends, or once the entry is complete.
Until someone has entered a valid email address, their entry can’t be resumed and no reminder is sent.
Errors and Limits
If a workflow has a problem, such as no root chain or no interactions, people see “This questionnaire is not available right now.”
If a workflow hasn’t synced yet, visitors see “This form isn’t ready yet.” Logged-in builders are asked to click Sync in the builder.
If SpruceTip is slow or unavailable, people are asked to wait a moment and click Next again. Their answers are kept.
File uploads are PDF only, up to 20 MB, or less if your server allows less.
To prevent abuse, starting, submitting and uploading are limited per visitor and per site each hour. People who reach a limit are told when to try again. People who can build workflows aren’t limited.
Entries and Reports
Go to SpruceTip → Entries and choose a workflow. Entries are listed with their date, email address and status: Not finished, Report queued, Creating report, Report sent or Report failed.
View shows every answer, grouped by chain. Uploaded files have a Download file link, which only administrators can use.
Report downloads a PDF of the answers. It includes the questions with Show in report turned on, from the chains the person went through.
Delete deletes the entry.
Who can see entries is set under Access in SpruceTip → Settings.

Questionnaire Styles
Go to SpruceTip → Questionnaire Styles to match the form to your brand. These styles apply to every questionnaire on the site. The colours are also used in the PDF reports and emails.
Brand: Accent, Accent light and Accent dark. A button can work out the light and dark shades from the accent for you.
Background and lines: the page background and line colours.
Text: the main and muted text colours.
Shape: card, field and button corners. Set button corners to 24 for fully round buttons.
Next button (optional): add your theme’s button classes, such as btn btn-primary, to use your theme’s button style.
The preview updates as you make changes. A check below it warns you if any colours are hard to read together.
Reset to defaults brings back the original styles.

Settings and Access
SpruceTip → Settings is for administrators only. Until a Gemini API key is saved, only the Gemini section is shown.
SpruceTip: your SpruceTip token.
Gemini: your Gemini API key, and the Default model used by workflows without an assistant. Click Refresh list to load the latest models.
Access: choose which roles can Build workflows and which can View and delete entries. Administrators always have both, and only roles that can build workflows can be given access to entries.
Saved keys are hidden. Click Replace to change one.
Deactivating and Removing Data
When you deactivate SpruceTip from the Plugins screen, you’re asked what to do with entry data:
Keep entry data: nothing is deleted.
Keep it for now, delete it if I delete the plugin: entries, reports, uploads and knowledge base files are removed if you later delete the plugin.
Delete all entry data now: entry data is removed before deactivating.
Workflows, assistants and settings are always kept.
Deactivating any other way, such as with a bulk action, deletes nothing.
