> For the complete documentation index, see [llms.txt](https://www.quillaudits.com/quillshield/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.quillaudits.com/quillshield/guides/getting-started/core-concepts.md).

# Core concepts

Orgs, projects, versions, pricing, wallet, full audits, and CI/CD checks.

## Organization

An **organization** is the tenant boundary. It owns projects, API keys, members, and audit history.

Roles (highest to lowest): `owner` · `admin` · `member` · `viewer`

* Mutating projects, keys, CI install, or invites requires **admin** or **owner**.
* Building and editing workflows, choosing the workflow and AI for an audit, and setting the default workflow also require **admin** or **owner**.
* Spending (quotes, orders, CI scans, share links, publish) requires **member** and above.
* **Viewers** are read-only.

## Wallet (per user)

Prepaid dollars, refund credits, and bonus/referral credit live on **your user wallet**, not on the org. New accounts receive **$50** signup credit once (bonus, 50% checkout cap, expires in 6 months). Dashboard checkout spends the signed-in user. **API keys** (CLI, MCP, Actions) spend the **org owner’s** wallet.

See Pricing & top-up.

## Project and version

A **project** is an audit target (`upload` or `git`). A **version** is a concrete snapshot of Solidity source. Git sources can be GitHub, GitLab.com, or any git URL the platform can clone.

**BLOC** (billable lines of code) is the scoped **nSLOC** of selected `.sol` files: comments and blank lines are stripped, then non-blank lines are counted. That BLOC total is what full-audit pricing uses.

## Pricing and payment

Full audits are priced in **USD** from BLOC on a **scope curve** (`QS-PAYG-USD-V6`):

* Floor **$49**, then charm pricing of `max(49, 3 × L^0.7)` (prices end in $x9)
* **Over 40,000 BLOC:** contact sales

By default, dashboard checkout runs the **QuillShield Audit Agent**, the full audit pipeline. In the audit's **Workflow** step you can choose another [workflow](https://www.quillaudits.com/quillshield/guides/guides/workflows.md) instead, at the same price. Light **CI/CD** scans are priced separately from delta SLOC.

```mermaid
flowchart LR
  Q[Quote] --> O[Order]
  O --> P[Payment]
  P --> A[Audit job]
```

| Object        | Meaning                                                                                                                                             |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Quote**     | Server price snapshot for a scoped version (about 7-day TTL). It also freezes the workflow version, the answers to its questions and the AI choice. |
| **Order**     | Payment intent against an accepted quote                                                                                                            |
| **Audit job** | Starts only after the order is `paid`                                                                                                               |

Checkout apply order: coupon or referral welcome, then **prepaid → refund → bonus**, then Stripe cash due. Bonus covers at most **50%** of the post-discount order.

Only **one** full audit can run per org at a time.

## Full audits vs CI/CD checks

| Kind                 | When to use                                                                                                         |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Full audit**       | New project, large change, or first baseline on a git repo                                                          |
| **CI/CD light scan** | GitHub pull requests and commits, or GitLab.com merge requests and commits, against a completed full-audit baseline |

Job statuses include `queued`, `building`, `running`, `paused`, `completed`, `failed`, and `cancelled`. Only a custom workflow running on your own AI can be `paused`: your Claude or ChatGPT plan hit its limit or signed out, or your provider key ran out of credits. Resume it within 7 days at no extra charge, or it is refunded.

## Workflows

A **workflow** is the plan an audit follows: what the AI agents look for, in what order, and what they report. Every audit runs exactly one workflow.

| Workflow                    | What it is                                                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **QuillShield Audit Agent** | QuillShield's full audit pipeline with verified proof-of-concept exploits. Every organization's default.                                          |
| **Official workflows**      | Focused workflows by QuillShield: Entry-point attack paths, Access-control consistency, Oracle and price manipulation, and Accounting invariants. |
| **Marketplace workflows**   | Published by other organizations after QuillShield's review.                                                                                      |
| **Your own workflows**      | Built by owners and admins in Workflow Studio, by describing in plain words what to look for.                                                     |

A workflow runs in **stages** of **agents**. The last stage reports the findings, and optional **follow-ups**, such as a Foundry proof of concept, run once for each finding. Every save creates a numbered **version** that never changes, and a quote freezes the exact version, the answers to the workflow's questions and the AI choice. Every workflow costs the same. See [Workflows](https://www.quillaudits.com/quillshield/guides/guides/workflows.md).

## Findings

Each finding has severity, title, description, impact, locations, and triage status (`open`, `acknowledged`, `fixed`, `false_positive`). You can comment, Ask AI, share a read-only link, publish the audit, or request expert validation. Findings from custom workflows also show **Workflow details**, such as tags, the attack path and what the follow-ups returned.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.quillaudits.com/quillshield/guides/getting-started/core-concepts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
