=== AskFolio: Grounded AI Q&A Panel ===
Contributors: jacobfractalist
Tags: portfolio, question-answer, ai, openai, file-search
Requires at least: 6.5
Tested up to: 7.1
Stable tag: 0.9.0
Requires PHP: 8.1
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Evidence-grounded Q&A for WordPress using your own OpenAI File Search vector store.

== Description ==

AskFolio adds a professional question-and-answer panel to a WordPress site. Visitors ask questions in plain language and receive answers grounded in source material the site owner has prepared and made available through an OpenAI File Search vector store.

It is designed for professional portfolios, organisations, practices and other information-rich sites where visitors need to ask useful questions about the work rather than use a general-purpose chatbot.

This WordPress.org package is the Free edition.

= What the Free edition provides =

* A public question-and-answer conversation panel for WordPress pages.
* Block and shortcode placement.
* Setup and connection testing for an owner-supplied OpenAI File Search vector store, with a guided Get started checklist.
* Configurable public copy, including panel title, welcome text, question-field placeholder, suggested prompts and unavailable message.
* Three front-end presentation styles: Minimal, Classic and Dark.
* Configurable panel width and accent colour.
* Configurable public live-response limits, including a per-visitor allowance and a site-wide daily cap.
* Fixed answer rules and safeguards.
* Server-side API-key handling. The plugin does not display or save the API key in WordPress settings.
* Safe unavailable behaviour when the profile is disabled, unconfigured or no longer has a current successful connection test.
* An optional "Powered by AskFolio" credit line under the panel. It is off by default and only appears if you switch it on.

Approved public evidence links shown under answers are not part of the Free edition.

= Designed for prepared professional knowledge =

AskFolio is intended for sites where the owner already has a body of approved material that can answer questions about a person, organisation, practice, project or body of work.

A typical setup is:

1. Prepare and approve the source documents outside the plugin.
2. Create and populate an OpenAI File Search vector store.
3. Add the API key server-side using the key name shown by the plugin.
4. Enter the vector store ID in AskFolio.
5. Test the connection.
6. Configure the public wording, appearance and limits.
7. Place the conversation panel on a page.

= Not a document-management system =

AskFolio does not upload documents, create vector stores, index a corpus or manage source files. Those are prepared separately by the site owner. The plugin is focused on WordPress presentation, configuration and a bounded public conversation interface.

The plugin uses the configured File Search store at answer time and is designed to keep responses grounded in the evidence available there, including acknowledging uncertainty where the source material does not support a confident answer.

= Abuse and cost controls =

The public panel spends from your own OpenAI account, so it is limited three ways: a per-visitor allowance (default 20 questions per hour), a site-wide daily cap (default 300, adjustable from 10 to 5000) and bounded question and history lengths. If your site is behind a CDN or proxy, set "Visitor address source" under Appearance & Limits so visitors are told apart correctly. Also set a monthly spend limit on your OpenAI project. Anyone who can load the page can ask questions, so the vector store should contain only material you are happy to expose.

== Installation ==

1. Install and activate AskFolio.
2. In the plugin's Setup screen, add the required OpenAI API key as a server-side constant in `wp-config.php` using the key name shown by the plugin (`WPIP_OPENAI_API_KEY`). The key itself is not stored in WordPress options.
3. Create and populate an OpenAI File Search vector store outside WordPress, then enter its vector store ID in the plugin.
4. Run the connection test.
5. Configure the visitor-facing wording under Conversation.
6. Choose a front-end design, width, accent colour and public live-response limits under Appearance & Limits.
7. Place the panel on a page using the AskFolio block or `[wp_interactive_portfolio]` shortcode.

A profile must be enabled and have a current successful connection test before it will accept public questions.

== Frequently Asked Questions ==

= Does AskFolio upload or index my documents? =

No. The plugin uses an existing OpenAI File Search vector store supplied and populated by the site administrator. It does not upload source documents, create a vector store or manage the corpus.

= Where is the OpenAI API key stored? =

The API key is supplied server-side, for example through `wp-config.php`, using the key name expected by the configured profile. AskFolio does not display the secret in wp-admin and does not save it in WordPress options.

= What data is sent to OpenAI? =

For a ready public profile, the plugin sends the bounded visitor question and bounded prior conversation history to OpenAI together with a File Search request for the vector store configured by the site administrator. See the External services section below for details and policy links.

= Can I control what visitors see before they ask a question? =

Yes. The Free edition provides configurable visitor-facing copy including the welcome message, question-field placeholder, suggested public prompts and unavailable message.

= What front-end designs are included? =

The Free edition includes Minimal, Classic and Dark presentation styles. Width and accent colour can also be configured. The designs are self-contained and do not depend on your theme.

= Can I limit public usage? =

Yes. The plugin provides configurable public live-response controls, including per-visitor limits and a site-wide daily cap.

= What happens if the OpenAI connection is unavailable? =

The plugin will not accept live public questions unless the configured profile is enabled and has a current successful connection test. An unavailable message is shown instead of exposing diagnostic information.

= Are approved evidence links under answers included in Free? =

No. Approved public evidence links under answers are a Premium feature.

= Is this a general-purpose AI chatbot? =

No. It is designed as a question interface for a prepared body of professional or organisational source material supplied by the site owner.

= Is this listing for the Free or Premium edition? =

This WordPress.org listing is for the Free edition. Premium-only capabilities are not included in the WordPress.org Free package.

== External services ==

AskFolio requires the OpenAI API to provide live answers. It uses the OpenAI Responses API and File Search against the vector store configured by the site administrator.

When a visitor submits a question to a ready profile, the plugin sends the bounded question and bounded prior conversation history to OpenAI together with a File Search request for the configured vector store. The request is processed using the site owner's OpenAI API account. Requests are made from the WordPress server to `api.openai.com`, never from the visitor's browser. The administrator's connection test and a brief check that the vector store is ready are also sent to OpenAI.

The plugin does not send the API key to the browser, does not save the API key in WordPress options and does not show raw provider error details to visitors.

OpenAI operates this external service. Relevant information is available at:

* OpenAI service: https://openai.com/
* Terms and policies: https://openai.com/policies/
* OpenAI Services Agreement: https://openai.com/policies/services-agreement/
* Service Terms: https://openai.com/policies/service-terms/
* Privacy Policy: https://openai.com/policies/row-privacy-policy/

= Why the plugin calls OpenAI directly =

WordPress 7.0 includes a provider-agnostic AI Client, with provider keys managed under Settings > Connectors. This plugin does not use it because it needs capabilities that a generic prompt interface does not provide: answering from an owner-supplied OpenAI File Search vector store through the Responses API, with retrieval required for historical questions. It also supports WordPress 6.5 and later, which do not have the AI Client, and it keeps the API key in a server-side constant rather than in a site-wide connector setting. The plugin therefore calls `api.openai.com` directly from the server, only for a profile that is enabled and has a current successful connection test, exactly as described above.

Site owners are responsible for ensuring that their source material, privacy notice and use of OpenAI are appropriate for their site and jurisdiction.

== Privacy ==

AskFolio does not store the OpenAI API key in WordPress options and does not expose it to visitors. Public conversation history held by the browser is bounded before it is sent with a request.

To apply the public live-response limits, the plugin keeps short-lived WordPress transients: a per-visitor counter keyed by a hash of the visitor's IP address and a site secret (the address itself is not stored), and a site-wide daily counter. It does not create a visitor account or a persistent visitor identity, and it sets no cookies. The Free edition does not include the Premium administrator conversation archive, analytics or telemetry.

Because visitor questions are sent to OpenAI when the public Q&A panel is used, site owners should disclose this external processing in their own privacy information. The plugin adds suggested wording to the WordPress privacy policy guide.

When the plugin is deleted, its settings and transients are removed.

== Source code and third-party libraries ==

The plugin's PHP, JavaScript and CSS are unminified and readable in the plugin folder. Two third-party browser libraries are bundled locally in `assets/js/vendor/`, unmodified from their upstream releases:

* [Marked](https://github.com/markedjs/marked/tree/v18.0.14) 18.0.14 (MIT), shipped unminified as `marked.js`.
* [DOMPurify](https://github.com/cure53/DOMPurify/tree/3.4.16) 3.4.16 (MPL-2.0 or Apache-2.0), shipped as the upstream minified `purify.min.js`; its readable source and build instructions are at the linked tag.

See `THIRD-PARTY-NOTICES.txt` for licence details. The Niche Clever logo in `assets/images/` is a brand asset included with the publisher's permission and is not licensed for reuse under the GPL.

== Screenshots ==

1. Three front-end designs: Minimal, Classic and Dark presentation styles using the same visitor conversation workflow.
2. Setup: connection checklist for the server-side OpenAI API key, File Search vector store, connection test and page placement.
3. Appearance & Limits: choose the panel style, width and accent colour, and configure public live-response limits.
4. Conversation: configure the welcome message, question placeholder, suggested public prompts and unavailable message.

== Support ==

Documentation and product support information:

https://nicheclever.co.uk/askfolio/

== Changelog ==

= 0.9.0 =

* Initial WordPress.org Free release.
* Public evidence-grounded Q&A panel using an administrator-supplied OpenAI File Search vector store.
* Minimal, Classic and Dark public presentation styles.
* Block and shortcode placement, configurable public copy, appearance controls and public live-response limits.
* Server-side API-key handling, connection readiness checks and safe unavailable behaviour.
