Getting started with Shilpi

Quick start

Shilpi is a WordPress theme, not a plugin. Install it, activate it, and the Shilpi menu appears in wp-admin with the dashboard, pages, templates, elements, Code Hub, form submissions, system information, fonts, icon libraries, project files, plugins, settings, skills and security screens.

1. Upload and activate the theme.
2. Open Shilpi › Templates and create a Header. Set it as the site default under Settings.
3. Open any page and choose Edit with Shilpi.
4. Paste body-only HTML, or start from an element in the palette.
5. Press Save. Autosave keeps a revision every minute in the meantime.

The dashboard

Four status cards sit across the top, and they are the fastest read on whether a site is healthy: the state of the AI workspace, how many production assets are cacheable front-end files, how many site health checks passed with their warnings and failures, and the recent activity from the last imports.

Below them are six tabs:

• Where things are: a jump-off to Pages, Templates, Elements, Code Hub, Form submissions, System Information, Fonts, Icon Libraries, Project Files, Plugins and Settings.
• Connect an AI agent: the server switch, the handshake test and the credentials.
• Production assets: which front-end files are ready to be cached.
• Recent imports: the last runs, with the most recent retained.
• AI instructions: see below.
• Licence: plan, activations and renewal.

Requirements

• WordPress 6.4 or newer, tested up to 7.1
• PHP 8.0 or newer, tested up to 8.3
• An administrator account for anything that touches PHP or JavaScript uploads
• HTTPS, if you plan to connect an AI agent over OAuth

The System Information screen runs a set of health checks on your install and reports capabilities, warnings and failures in one place, start there when something behaves unexpectedly.

Installing the theme

Upload the ZIP under Appearance › Themes › Add New and activate. The builder, the design system, templates, forms and the Code Hub are available immediately.

Add-ons & plugins

The theme deliberately stays small. Features that only some sites need ship as free companion plugins instead, and Shilpi › Plugins is a directory of them with install and activate in one click. There is no ZIP to download and no licence key to paste: each plugin then updates itself from shilpibuilder.com through WordPress’s own Update URI mechanism.

The most important one today is Shilpi WooCommerce Kit, which carries the entire storefront. See WooCommerce Kit below.

Activating a licence

Open Shilpi › Dashboard › Licence and paste the key from your purchase email. The panel then reports your plan, how many of your sites are activated, and when the licence renews.

A licence unlocks three things: the AI layer, automatic updates and support. The MCP server needs an active key to answer at all, without one, both endpoints return 404 and no agent credential will authenticate.

Everything else works without a licence, and keeps working if one lapses: the visual builder, the design system, templates and routing, native forms and sliders, the Code Hub, and every page you have already published. Your visitors never see a difference, and the server’s on/off switch is remembered, so activating a key brings the AI layer straight back.

The three fields

Every Shilpi page or template is stored as three plain fields. That is the entire storage model, and it is what keeps the site portable. Here is the reasoning behind storing pages as code.

Page HTML

Body-only semantic markup. No html, head or body wrapper, Shilpi supplies those. Two rules matter: no inline style attributes, and no style blocks inside the page HTML.

Visual decisions belong in reusable classes and variables instead, which is what makes a change on one page able to reach the whole site.

<section class="section">
  <div class="container stack">
    <h1 class="heading-xl">{post:title}</h1>
    <p class="lead">{post:excerpt}</p>
    <article data-shilpi-post-content></article>
  </div>
</section>

Page CSS

A real stylesheet scoped to this page. Use it for rules that genuinely belong to this page alone. Anything reusable belongs in a global class, where the builder and an agent can both find it.

Page JS

Focused behaviour for this page. Site-wide behaviour belongs in Code Hub › Global JS.

The cascade

Order is fixed and worth memorising, because it explains every “why is this not applying” question you will ever have:

1. Design variables: the tokens
2. Global classes: reusable styling
3. Global CSS: resets and base rules for every page
4. Page CSS: this page’s exceptions, printed last

Page CSS overrides all of them. That is by design: the page is the last word about itself.

Design variables

Open Variables in the builder toolbar. Each variable can carry a value per breakpoint: Wide from 1500px, Desktop as the base, Tablet to 1024px and Mobile to 767px.

Reference a variable in class CSS as var(--name). A variable may reference another, --font-heading: var(--font-body) is valid, and useful when a client changes their mind about one typeface and not the other. See how responsive design tokens work in practice.

Global classes

When you style an element on the canvas, Shilpi creates or extends a class rather than writing an inline style. This is the single habit that makes a Shilpi site maintainable: by the end of a build you have a small vocabulary of classes, not a thousand one-off declarations.

Name classes for what they are, not what they look like. .card survives a redesign; .blue-box-2 does not.

Your first page

1. Create a WordPress page and choose Edit with Shilpi.
2. Drop a Section, then a Container inside it.
3. Add a Heading and a Basic Text.
4. Select the section and set padding using a spacing variable rather than a raw pixel value.
5. Switch to the Tablet and Mobile views and confirm the result.
6. Save, then Preview.

If you already have static HTML, skip all of that: open Page code, paste the body markup, and start selecting elements on the canvas.

Templates & routing

Templates come in eight types, each mapping onto how WordPress already routes requests: Header and Footer (site defaults, overridable per page), Single, Archive, Search, 404, Loop and Part.

The slug is the assignment. There is no condition builder to configure afterwards, name the template the way the WordPress template hierarchy names it and Shilpi matches it to the request:

// most specific wins
single-post-my-slug   // one post
single-product        // every product
single                // every single post

archive-category-news // one category
archive-category      // all categories
archive               // the fallback archive

home                  // the posts page
search                // search results
404                   // not found

A Loop template is rendered once per post by a loop container that names it, design the card once and let the loop repeat it. Because a Part carries a shortcode, it can appear inside a classic post, a Gutenberg block or another plugin’s output, useful when only half the site is yours to rebuild.

Dynamic tokens

Tokens resolve at render time and can be typed directly into markup or chosen from the picker.

// site
{site:title}   {site:tagline}   {site:url}   {year}

// menus and parts
{menu:primary}   {part:cta-band}

// post
{post:title}     {post:excerpt}    {post:date}
{post:url}       {post:terms}      {post:reading_time}
{post:image}     {post:image_alt}  {post:image:large}
{post:prev_url}  {post:next_url}   {post:comments_count}

// archive, term and search templates
{archive:title}  {archive:description}  {archive:results_count}
{term:name}      {term:description}     {term:image}
{search:query}

// author and custom fields
{author:name}    {author:bio}      {post:meta:your_field}

// render slots
data-shilpi-post-content   data-shilpi-comments
data-shilpi-pagination     data-shilpi-loop

Forms & mail

Write an ordinary form and add data-shilpi-form="name". Give every input a lowercase name attribute, that is the column in the database, so decide it once at the start.

Submissions appear under Shilpi › Forms. Mail settings, recipient, transport, SMTP credentials and the delivery log, sit on the Mail tab beside the submissions they belong to. Set Keep submissions for to a number of days if you would rather not store personal data forever.

SEO & metadata

Every page and post carries its own SEO record: title, meta description, canonical URL, robots directives and the social card image. Set it in the builder, or let an agent set it as part of the same run that builds the page.

If you already run Yoast or RankMath, keep them. Shilpi reads the metadata that is already there rather than competing for the same fields, nothing you have written gets overwritten by installing the theme.

Menus & taxonomies

Menus are ordinary WordPress menus. Create one, order its items, and assign it to the Primary or Footer location, then render it anywhere with {menu:slug}, no shortcode and no widget area required.

Taxonomies work the same way: register or populate categories, tags and custom taxonomies, then point a query loop at one and give it an archive-category-… template to render into.

WooCommerce Kit

As of Shilpi 1.9 the theme carries no storefront code at all. The component runtime, the builder elements and the commerce skin, about 3,200 lines, all live in Shilpi WooCommerce Kit, a free plugin you install from Shilpi › Plugins.

Once it is active, a WooCommerce group appears in the element palette with 24 elements. Six of them are complete and are the fast default:

• Product Grid: limit, columns, category, order, sale, featured, inherit
• Single Product: a product ID, or 35 inside a template
• Add to Cart: a product ID and a quantity
• Cart, Checkout and My Account: the native, session-aware flows

The other eighteen are composable pieces, for when the design matters more than the speed: Woo Breadcrumbs, Store Notices, Product Gallery, Product Title, Product Rating, Product Price, Short Description, Product Stock, Product Add to Cart, Product Meta, Product Tabs, Related Products, Upsells, Product Categories, Result Count, Product Ordering, Mini Cart and Cart Count. Arrange them in any grid, reorder them, drop the ones you do not want, and style each with ordinary Shilpi classes.

What gets stored is readable configuration, not generated WooCommerce markup:

<div class="woocommerce-products sh-woo-element"
     data-shilpi-woo="products"
     data-woo-limit="8" data-woo-columns="4"
     data-woo-orderby="date"></div>

Shilpi translates data-shilpi-woo and the data-woo-* attributes into an allowed native shortcode at render time, which is why prices, stock, cart state, checkout validation and account data all stay live. Never paste the rendered preview markup back into the document.

Shilpi › WooCommerce also carries the storefront behaviour WooCommerce normally leaves to the theme: product labels, variation swatches, a sticky buy bar and catalog mode.

Product templates

Product routes are builder-authorable through two fixed slugs, exactly as the rest of the template hierarchy works. single-product is stored as a Single template, archive-product as an Archive template. More specific taxonomy templates still win, and product categories and tags fall back to archive-product.

Two attributes carry the whole thing. On a single-product template the host has to resolve against the current product, and on the archive the grid has to inherit WordPress’s own query, which is what preserves Shop, category filtering, ordering and pagination:

// single-product
<div data-shilpi-woo="product" data-woo-id="35"></div>

// archive-product
<div data-shilpi-woo="products"
     data-woo-inherit="true"
     data-woo-columns="4"></div>
<nav data-shilpi-pagination></nav>

The granular elements take data-woo-id too, which is what makes a fully custom product card possible inside an ordinary Shilpi loop: the card markup is yours, and only the price and the add-to-cart form come from WooCommerce.

Design packs

Cart, Checkout, My Account, product and shop-archive pages are the least enjoyable part of any store build, so the Kit ships finished designs for them. A pack imports in one step and undoes in one more.

Run the plan step first. It reports exactly what an import would create and what it would replace, before anything is written, which is the version to show a client rather than the version you have already applied.

Cart, checkout and account keep WooCommerce’s own native logic throughout. Shilpi styles the output through a route-scoped commerce skin, variables and deliberate overrides, and never replaces the checkout flow. After any storefront change, walk Product to Add to Cart to Cart to Checkout without placing an order, then empty the cart again, and check both desktop and mobile.

What the agent can and cannot do here

The MCP surface for commerce is deliberately bounded. An agent can read store status, create and assign the Shop, Cart, Checkout and My Account pages, configure store settings, list products and save simple ones, and switch the storefront behaviour described above.

It cannot reach customers, orders, addresses, payments or arbitrary order metadata. That boundary is a privacy decision, not an oversight, and it is not configurable.

Connecting an agent

1. Activate a licence on the Licence tab. The MCP server does not answer without one.
2. Open Shilpi › Dashboard › Connect an AI agent.
3. Confirm the server is on, and press Test server: it performs a real authenticated MCP handshake rather than pinging a URL.
4. Choose OAuth (recommended). The agent signs in through the browser and no password is copied into a config file.
5. If your client cannot do OAuth, create a WordPress Application Password instead.
6. Copy the brief from the AI instructions tab and paste it at the top of your first message.

Once connected, the agent has a fixed set of scoped abilities: pages and templates, variables and global classes, menus, taxonomies, SEO, PHP snippets, script files, fonts, media and whole-site import, plus whatever an active companion plugin adds, such as the WooCommerce tools from the Kit. It has no filesystem access, no SSH and no way to reach wp-config.php. We wrote up why the boundary is drawn at abilities rather than access.

Turning the server off removes both MCP endpoints. Existing credentials then cannot edit the site, which makes it a genuine kill switch rather than a setting. A lapsed licence has the same effect, and the panel says so rather than leaving you to guess.

Skills & instructions

Two Markdown skills ship with the theme and can be downloaded from Shilpi › Skills: shilpi-theme for everything the theme owns, and wordpress-core for native posts, pages, media, menus, users and settings.

Active companion plugins can add their own, so installing the WooCommerce Kit gives the agent a storefront skill it did not have a moment earlier. Those plugin skills are code-backed and read-only, and they disappear cleanly when the plugin is deactivated.

You can also upload your own Markdown skill to add house conventions; uploading the same slug again updates it.

Temporary permissions

Risky capabilities are temporary permissions, not settings you turn on and forget. Shilpi › Security shows how many are currently open, and closes every one of them with a single Turn off temporary access button.

Under Temporary file access, enable only the file types the current job needs. WordPress capabilities and Shilpi validation still apply on top:

• Sanitised SVG uploads: scripts, embedded HTML, event handlers and external references are stripped before storage.
• JSON project-file uploads: only valid JSON objects or arrays, up to the Shilpi upload limit.
• JavaScript project-file uploads: executable, so it requires an administrator-level trusted account and is validated before storage.

PHP access in the Code Hub is the fourth, and the one worth closing first when you finish a build. Closing any of these never deletes anything: existing media, project files and snippets stay exactly where they are.

WordPress hardening

The same screen carries a set of WordPress hardening switches. They are all reversible, and none of them edits wp-config.php or any server file, so nothing here can leave you locked out of your own site.

• Block dashboard file editors: prevents editing plugin and theme source in wp-admin. Updates still work.
• Disable XML-RPC: recommended, unless a mobile app or a legacy integration uses xmlrpc.php.
• Use generic login errors: stops the login form revealing whether a username or an email exists.
• Hide the WordPress generator version: removes the version from public page and feed output.
• Hide public REST user listings: signed-in users keep normal access, public /wp/v2/users requests are blocked.
• Disable application passwords: only when this site does not connect to any app through them.