QonQrete Quickstart

Version: v1.4.5 Release context: v1.4.5 - MLcon Edition

This is the shortest accurate path to get QonQrete running.

Option A: IDE-First (Recommended)

VS Code

Install the QonQrete extension from the VS Code Marketplace
Open any project folder
Run “QonQrete: Deploy to Workspace” from the Command Palette (Ctrl+Shift+P)
Run “QonQrete: Create Task File” — edit the starter tasq.md to describe your build task
Run “QonQrete: Run Tasq” — runs the default task file directly; auto-init handles the container image build on first run

IntelliJ / JetBrains

Install the QonQrete plugin from the JetBrains Marketplace
Open any project
Run “QonQrete: Deploy to Workspace” from the action search (Ctrl+Shift+A)
Run “QonQrete: Create Task File” — edit the starter tasq.md
Run “QonQrete: Run Tasq” (Ctrl+Alt+Q) — runs the default task file directly, auto-init on first run

What happens

my-project/
  tasq.md                  ← you edit this
  .qonqrete/               ← runtime (auto-deployed, gitignored)
    qonqrete.sh
    worqspace/
    qrane/
    worqer/
    Dockerfile
    ...

The IDE uses your chosen task file directly. tasq.md remains the default starter file, and you never need to touch the hidden runtime directory.

Option B: CLI (Power Users)

Prerequisites

Docker or Podman
At least one AI provider API key

export OPENAI_API_KEY='...'
export GOOGLE_API_KEY='...'      # or GEMINI_API_KEY
export ANTHROPIC_API_KEY='...'
export DEEPSEEK_API_KEY='...'
export QWEN_API_KEY='...'

1. Install + init runtime

curl -fsSL https://qonqrete.sh/install.sh | bash
./.qonqrete/qonqrete.sh init

2. Edit the task

tasq.md

3. Run QonQrete

./.qonqrete/qonqrete.sh run -f tasq.md
./.qonqrete/qonqrete.sh run -f tasq.md --auto -N
./.qonqrete/qonqrete.sh run -f tasq.md --seed-repo
./.qonqrete/qonqrete.sh status
./.qonqrete/qonqrete.sh audit

-N / --no-sync skips only the final repo-root sync-back step. Qage/Qonstruction output (including qodeyard/) remains available.

4. Resume / Clean

./.qonqrete/qonqrete.sh resume
./.qonqrete/qonqrete.sh clean
./.qonqrete/qonqrete.sh clean -A

If you are running directly from a full source checkout (repo-developer mode), ./qonqrete.sh remains valid.

IDE Commands Reference

Both VS Code and IntelliJ support the same commands:

Command	What it does
Deploy to Workspace	Install runtime into `.qonqrete/`
Create Task File	Create starter `tasq.md` at project root
Configure Run	Set sensitivity, cycles, mode, engine
Run Tasq	Run the default task file directly with auto-init when needed
Run as QonQrete Tasq	Run any markdown file directly as task input
Resume Run	Continue from a previous qage
Clean Qages	Delete old qage directories

Recommended first-run sanity checks

After a successful run, verify these exist:

.qonqrete/worqspace/qage_YYYYMMDD_HHMMSS/
.qonqrete/worqspace/qage_.../run-manifest.v1.json
.qonqrete/worqspace/qage_.../task/task-spec.v1.json
.qonqrete/worqspace/qage_.../validation/validation-bundle.v1.json
.qonqrete/worqspace/qage_.../realization/realization-bundle.v1.json
.qonqrete/worqspace/qage_.../verdict/inspection-verdict.v1.json
.qonqrete/worqspace/qage_.../qodeyard/
.qonqrete/worqspace/qage_.../build/attempts/

Cost Confirmation Gate

To require confirmation before running after cost estimation:

# In worqspace/config.yaml
options:
  cost_confirmation_gate: true

The GateQeeper will prompt you to confirm after CalQulator shows the cost estimate.

Validation Reality

Deterministic validation in the current bridge is strongest for Python. Other stacks still run through the workflow, but deterministic compile/test depth is not yet equivalent.

Configuration (v1.4.5)

This page summarizes the active runtime configuration model from worqspace/config.yaml and worqspace/pipeline_config.yaml.

Core Files

worqspace/config.yaml
worqspace/pipeline_config.yaml

Key Sections in `config.yaml`

retry
repair
ai_budgeting
interleaved
verification
agents
options

Repair and Iteration Controls

repair.max_attempts_per_build_pass: bounded same-run repairs per build pass
options.max_total_iterations: cap for total build + repair passes
options.max_build_passes: build-pass cap
Same-run repairs consume total-iteration budget but do not increment build-pass count.

ConstruQtor Coding Modes

agents.construqtor.coding_mode supports:

heredoc
direct
hybrid (default)

hybrid default policy:

new files use heredoc
existing files use direct
deterministic escalation can force heredoc when direct transport becomes fragile

Repo Seeding and Sync Controls

Default run starts from empty qodeyard/
--seed-repo (or legacy --sqrapyard) seeds repository content into qodeyard before run
Default behavior syncs changed outputs from qage back to repo root
-N/--no-sync skips only repo-root sync-back and keeps outputs in qage/qonstruction paths

Provider and Model Configuration

Providers supported in current runtime:

openai
gemini
anthropic
deepseek
qwen
openrouter
venice
mlx
llama-cpp
local (non-remote helper agents)

Current default primary-agent alignment in committed config:

qrystallizer: venice / deepseek-v3.2
instruqtor: venice / deepseek-v3.2
construqtor: venice / deepseek-v3.2
inspeqtor: venice / deepseek-v3.2
calqulator: gemini / gemini-2.5-flash-lite

Required and Optional Environment Variables

Common provider variables:

OPENAI_API_KEY
GOOGLE_API_KEY
GEMINI_API_KEY
ANTHROPIC_API_KEY
DEEPSEEK_API_KEY
QWEN_API_KEY
OPENROUTER_API_KEY
VENICE_API_KEY
MLX_API_KEY
LLAMA_CPP_API_KEY

Notes:

Venice requires VENICE_API_KEY and does not fall back to OPENAI_API_KEY.
mlx and llama-cpp require per-agent api_base_url for real usage.
MLX_API_KEY and LLAMA_CPP_API_KEY are optional.

Useful Runtime Commands

./.qonqrete/qonqrete.sh run -f tasq.md
./.qonqrete/qonqrete.sh run --seed-repo
./.qonqrete/qonqrete.sh run -N --qonstruction-name demo_run
./.qonqrete/qonqrete.sh status
./.qonqrete/qonqrete.sh audit
python worqer/qontextor.py --capabilities
python worqer/qompressor.py --capabilities

For the full authoritative details, see the synced docs:

doc/DOCUMENTATION.md
doc/ARCHITECTURE.md
doc/QUICKSTART.md

QonQrete Architecture

Version: v1.4.5 Release context: v1.4.5 - MLcon Edition

This document describes the current repository architecture as shipped in the v1.4.5 snapshot.

High-level model

QonQrete is split into three layers:

Core runtime — the CLI entrypoint, orchestrator, agents, config, and generated artifacts
Workspace data plane — worqspace/, qages, qonstructions, and context caches
IDE integrations — VS Code and IntelliJ / JetBrains wrappers around the CLI workflow

Top-level layout

qonqrete/
├── qonqrete.sh                # Host entrypoint
├── qrane/                     # Orchestrator layer
├── worqer/                    # Agent and utility layer
├── worqspace/                 # Config + runtime data
├── doc/                       # Documentation set
├── vscode-extension/          # VS Code integration
└── intellij-plugin/           # JetBrains integration

Layer 1 — Host entrypoint

`qonqrete.sh`

Responsibilities:

command parsing (init, run, resume, status, audit, clean, clean-outputs)
OS detection
container engine detection
build backend detection
qage creation and manifest-linked workspace seeding
Qonstruction save / resume / clean flow

The current CLI supports:

Podman (default auto-detected path)
Docker (explicit via --docker or CONTAINER_ENGINE=docker)

It also provides flags for:

autonomous vs user-gated operation
operational mode
briq sensitivity
total-iteration cap / build-pass cap
optional explicit repo seeding (--seed-repo, with legacy -s/--sqrapyard alias)
optional repo-root sync suppression (-N/--no-sync)
explicit runtime forcing
qonstruction save naming

Layer 2 — Qrane orchestrator

`qrane/`

Main files:

qrane.py — orchestrator main loop
loader.py — CLI/UI helper behavior
paths.py — path manager
lib_funqtions.py — pricing helpers

Runtime responsibilities

Qrane:

reads worqspace/config.yaml
resolves final mode / sensitivity / execution caps (total iterations, build passes, repair attempts)
validates required API keys for configured providers
runs the configured pipeline in canonical stage order
maintains the run manifest and audit trail
performs bounded repair and continuation routing
distinguishes queued-next-pass resume from interrupted-active-pass resume to preserve truthful pass lineage
derives validation execution mode from explicit validation/smoketest evidence so markdown presence alone does not overclaim executed coverage

Layer 3 — Agent layer

`worqer/`

The repo currently contains these notable agents/utilities:

AI / pipeline agents

qrystallizer.py — canonical intake agent; synthesizes high-quality goals and clarified intent context from user answers when the raw task is vague, falling back truthfully to raw context when answers are unresolved.
qonstrictor.py
instruqtor.py — planning agent; consumes clarified intent and synthesized goals as first-class inputs to ensure accurate briq decomposition.
construqtor.py — generates/modifies code in qodeyard/ via heredoc (Markdown fences), direct (tool-based), or deterministic hybrid coding mode. Supports iterative repair-forward validation in a validation-root sandbox.
inspeqtor.py

local / deterministic helpers

calqulator.py
qontextor.py
qompressor.py
qontrabender.py
qonfirmer.py
qualifier.py
runtime_capabilities.py
lib_ai.py
lib_security.py

Pipeline order

The current committed worqspace/pipeline_config.yaml bridges the canonical order as:

qrystallizer → qonstrictor → instruqtor → calqulator → construqtor → qontextor/qompressor/qontrabender (support services) → inspeqtor

Additional notes:

qrystallizer is the canonical intake implementation
intake clarification can pause runs in explicit BLOCKED / RUN_WAITING_FOR_INPUT state when readiness is NOT_READY
clarification-blocked resume re-enters cycle-1 intake semantics so cycle_1_only intake stages are not skipped
qontrabender is trigger-driven rather than a simple always-on stage
qodeyard/ remains the mutable build surface inside a run, while the manifest is the authoritative linkage layer
bloq.d/, qontext.d/, and qache.d/ are support artifact domains, not canonical lifecycle stages

Artifact model

Each run gets a dedicated Qage directory:

worqspace/qage_YYYYMMDD_HHMMSS/

Typical contents:

tasq.d/
task/
qontract.d/
briq.d/
qontract.d/
planning/
estimation/
qodeyard/
exeq.d/
build/
validation/
realization/
verdict/
continuation/
reqap.d/
qontext.d/
bloq.d/
struqture/
audit/
run-manifest.v1.json

Meaning of the main directories

tasq.d/ — compatibility pass task material (cyqle{N} folders map to global iteration index)
task/ — canonical task spec, clarification log, and intake summary
qontract.d/ — Qonstrictor and QONTRACT artifacts
briq.d/ — generated work units
qontract.d/ — human + machine-readable contract
planning/ — execution blueprint, validation plan, build groups, completion criteria
estimation/ — estimation artifacts
qodeyard/ — generated / modified code build surface
exeq.d/ — execution summaries
build/ — build-group reports and per-attempt staged/recovery evidence
validation/ — validation bundles
realization/ — observed-outcome bundles
verdict/ — inspection verdicts and repair plans
continuation/ — continuation metadata
reqap.d/ — review and iteration recap output
qontext.d/ — deterministic structural context output
bloq.d/ — compressed structural skeletons (Python, shell, JS/TS, HTML/CSS first-class; optional Tree-sitter fallback for other parseable code)
struqture/ — per-agent logs
audit/ — manifest-linked audit timeline and event stream

QONTRACT enforcement model

The repository uses a contract-first model for later build passes and repair passes.

Generation

On the first build pass, InstruQtor generates:

qontract.d/qontract.md
qontract.d/qontract.json

Enforcement

Later stages use:

fail-fast checks in qrane/lib_qrane.py when contract artifacts are required but missing
qonfirmer.py for deterministic AST-based verification

Current documented invariant types include:

forbidden imports
schema field expectations
forbidden field names
ID type rules
monotonic ID strategy patterns
required endpoint checks

Context / memory layers

QonQrete uses multiple context layers to keep prompts smaller and more structured:

Layer	Directory	Role
Task	`tasq.d/`	current objective
Contract	`qontract.d/`	project rules / constitution
Code	`qodeyard/`	current truth source
Execution	`exeq.d/`	build summaries
Review	`reqap.d/`	review output
Skeletons	`bloq.d/`	compressed code structure
Structural context map	`qontext.d/`	symbol / relationship hints
Cache	`qache.d/`	Qontrabender payloads when used

Security model

Important security properties in the repo:

Qage container isolation
read-only root filesystem with writable workspace paths
reduced capability model for container execution
non-root runtime with no runtime privilege transition
path validation and jail enforcement in lib_security.py
API timeout / retry safety in lib_ai.py

IDE integration architecture

VS Code

vscode-extension/ wraps the existing CLI rather than replacing it.

It contributes:

command palette commands
context menu commands
sidebar webview
status bar state
settings-backed run config
terminal-driven execution

The extension currently assumes a repo-local QonQrete project and looks for project markers such as:

qonqrete.sh
worqspace/config.yaml
tasq.md

IntelliJ / JetBrains

intellij-plugin/ provides a parallel integration path.

It includes:

Gradle-based plugin project
plugin README / changelog
tool-window-oriented UX
settings and packaging path for manual install / future store publishing

Current repo-local model

This repository snapshot does not yet implement a fully centralized shared engine architecture. The active model is still:

project contains qonqrete.sh + worqspace
IDE integration detects that project
IDE calls the repo-local CLI

That should be documented honestly until a central-engine bootstrap workflow actually exists in the codebase.

Data flow summary

flowchart TD
    User[User / IDE] --> CLI[qonqrete.sh]
    CLI --> Qage[Qage container run]
    Qage --> Qrane[Qrane orchestrator]
    Qrane --> Instruqtor[InstruQtor]
    Qrane --> Calqulator[CalQulator]
    Qrane --> Construqtor[ConstruQtor]
    Qrane --> Inspeqtor[InspeQtor]
    Qrane --> Qontextor[Qontextor]
    Qrane --> Qompressor[Qompressor]
    Construqtor --> Qodeyard[qodeyard]
    Inspeqtor --> Reqap[reqap.d]
    Instruqtor --> Briq[briq.d]
    Instruqtor --> Qontract[qontract.d]
    Qontextor --> Qontext[qontext.d]
    Qompressor --> Bloq[bloq.d]

Qontextor extractor model

Qontextor local mode is now a shared structural graph pipeline with registry-dispatched extractors. Today the first-class deterministic paths in the shipped/provisioned environment are:

Python AST structural graphing
shell structure and command/env mapping via shfmt -tojson in the shipped environment
JS/TS module, DOM, and storage mapping via a repo-shipped TypeScript helper
HTML/CSS linkage graphing via repo-shipped parse5/postcss helpers

This path is structural and offline-safe by default. Reduced local environments can fall back, and the active capability set is surfaced via the capability report and run manifests.

Workspace Deployment Model (v1.2.0+)

Starting with v1.2.0, the IDE integrations implement a workspace-local hidden runtime deployment model:

my-project/
  tasq.md                    ← user-facing task file
  .qonqrete/                 ← hidden runtime (gitignored)
    qonqrete.sh
    VERSION
    Dockerfile
    qrane/
    worqer/
    worqspace/
      config.yaml
      pipeline_config.yaml
      tasq.md                ← synced from root before each run
      qage_YYYYMMDD_HHMMSS/

Key design decisions

Script-relative runtime preserved: qonqrete.sh still derives SCRIPT_DIR and sets WORKSPACE_DIR relative to itself. Deploying the full repo structure into .qonqrete/ means everything works without any runtime architecture changes.
User-facing tasq at workspace root: The IDE syncs <workspace>/tasq.md → .qonqrete/worqspace/tasq.md before each run. Users never need to edit hidden files.
Auto-init on first run: If the container image doesn’t exist, the IDE runs ./.qonqrete/qonqrete.sh init automatically.
Versioned images: Container images are tagged qonqrete-qage:<version> (for example qonqrete-qage:1.4.0), with :latest plus an untagged compatibility alias.
Identical behavior in both IDEs: VS Code and IntelliJ implement the same commands, same deployment model, same sync behavior.

Deployment source

Primary: versioned GitHub release zip (qonqrete-v1.4.5.zip) Fallback: shallow git clone if zip download fails

Testing and Validation (v1.4.5)

Core Runtime Checks

./.qonqrete/qonqrete.sh init
./.qonqrete/qonqrete.sh run -f tasq.md
./.qonqrete/qonqrete.sh status
./.qonqrete/qonqrete.sh audit
./.qonqrete/qonqrete.sh clean

Capability Reporting

python worqer/qontextor.py --capabilities
python worqer/qompressor.py --capabilities

Python Test Suite (repo-local)

pytest

Validation Reality

deterministic validation is strongest for Python in the current bridge
other stacks still benefit from orchestration, artifact capture, and AI inspection
validation_execution_mode only reports executed coverage when executed evidence exists

Contexting in QonQrete (v1.4.5)

QonQrete uses file-based context layers so each run is inspectable and grounded.

Context Layers

Layer	Location	Purpose
Task	`tasq.d/` and `task/`	Current objective and clarified intake spec
Contract	`qontract.d/`	QONTRACT + Qonstrictor constraints
Code	`qodeyard/`	Canonical build output inside the qage
Execution	`exeq.d/`	Build summaries and changed scopes
Review	`reqap.d/` and `verdict/`	Inspection recap, verdicts, repair plan
Structure	`bloq.d/`	Deterministic compressed code skeletons
Structural map	`qontext.d/`	Deterministic context graph output
Cache payload	`qache.d/`	Qontrabender output when enabled

Why This Matters

context is visible on disk, not hidden in chat history
support agents can reuse structure artifacts instead of raw full-tree payloads
review and continuation decisions are tied to explicit artifacts and manifests

Current Runtime Notes

Qontextor default path is deterministic structural extraction.
Qompressor default path is deterministic multi-language skeletonization.
Tree-sitter is optional and only active when explicitly installed.

Capability Checks

python worqer/qontextor.py --capabilities
python worqer/qompressor.py --capabilities

QonQrete Documentation

Version: v1.4.5 Release context: v1.4.5 - MLcon Edition

This document is the synced technical reference for the current v1.4.5 repository snapshot.

Current release deltas (`v1.4.5 - MLcon Edition`)

Final inspection paths now treat final qodeyard/ files as authoritative evidence over relay/log snippets.
Frontend localStorage deterministic validation now supports compact constant/alias/object key indirection.
Verdict synthesis downgrades advisory briq-review noise when deterministic gates pass.
Qrane/ConstruQtor heartbeat chatter is removed from terminal output.
Streamed heredoc terminal rendering is concise by default, with TTY-only hotkeys:
- TAB => raw stream view
- Shift+TAB => concise view
Launcher now supports -N/--no-sync to skip repo-root sync-back and keep run output in Qage/Qonstruction paths.
Primary agent defaults are aligned to venice / deepseek-v3.2, and ConstruQtor default coding mode is hybrid.

1. What QonQrete is
2. Current repository scope
3. Core execution flows
4. Agent reference
5. QONTRACT system
6. Context and memory layers
7. Configuration reference
8. Providers and API keys
9. IDE integrations
10. Security model
11. Current limitations
12. Workspace Deployment (v1.2.0+)
13. Cost Confirmation Gate (GateQeeper)
14. OpenRouter Provider Support
15. Venice Provider Support (v1.3.12)
16. MLX and Llama-cpp Provider Support (v1.3.12)

1. What QonQrete is

QonQrete is a structured AI construction loop for building software inside a hardened runtime. It takes a high-level task, decomposes it into briqs, generates or modifies code, reviews the result, and optionally continues into more build/repair passes when the runtime allows it.

The system is designed around:

local file visibility
repeatable pipeline stages
contract enforcement
container isolation
clear review artifacts

2. Current repository scope

The current repo includes:

Core runtime

qonqrete.sh
qrane/
worqer/
worqspace/

IDE integrations

vscode-extension/
intellij-plugin/

Documentation

doc/

Starting with v1.2.0, both IDE integrations implement a workspace-local deployment model. Users run “Deploy to Workspace” to install the runtime into .qonqrete/. The runtime remains script-relative and repo-shaped, deployed locally per workspace.

3. Core execution flows

3.1 Initialization

./.qonqrete/qonqrete.sh init

Initialization:

detects OS
detects or accepts explicit runtime engine
detects build backend
builds the Qage image

Supported runtime paths in the repo:

Podman (default auto-detected path)
Docker (explicit via --docker or CONTAINER_ENGINE=docker)

3.2 Fresh run

./.qonqrete/qonqrete.sh run -f tasq.md
./.qonqrete/qonqrete.sh run -f tasq.md --auto -N

Current run flow:

validate runtime prerequisites
validate required config/task files
create a new qage_YYYYMMDD_HHMMSS
default to an empty qodeyard/ (no repo seed) and copy task material into tasq.md + tasq.d/cyqle1_tasq.md
optionally seed repository code into qodeyard/ when --seed-repo (or legacy -s/--sqrapyard) is used
launch the container
let Qrane execute clarification, qonstrictor, planning, build, validation/realization, and inspection
by default, sync changed outputs back to repo root with non-seeded collision protection
when -N/--no-sync is passed, skip only that repo-root sync-back and keep output in Qage/Qonstruction paths (lineage.repo_sync_mode = no_sync)
optionally save as a qonstruction

3.3 Resume

./.qonqrete/qonqrete.sh resume
./.qonqrete/qonqrete.sh resume -q qage_YYYYMMDD_HHMMSS

Resume flow:

choose an existing qage (interactive or direct)
copy the selected qage into a new qage
refresh workspace-driven config/task material
continue as a new run with previous state available
if execution.state.pending_next_pass_kind is present, resume honors that queued pass exactly
if no queued next pass exists and the previous run shows an interrupted active pass, resume restores that interrupted active pass semantics (including interrupted repair passes)
if legacy manifests are missing explicit resume markers, resume uses conservative inference and avoids silently fabricating a different pass kind
if the source run is blocked on intake clarification (RUN_WAITING_FOR_INPUT + BLOCKED), resume re-enters cycle-1 clarification semantics instead of skipping cycle-1-only intake stages

3.4 Clean

./.qonqrete/qonqrete.sh clean
./.qonqrete/qonqrete.sh clean -q qage_YYYYMMDD_HHMMSS
./.qonqrete/qonqrete.sh clean -A

Clean flow supports:

interactive delete
direct delete
delete all

4. Agent reference

4.1 `qrystallizer.py`

Canonical intake / clarification stage.

cycle-1-only behavior
writes task/task-spec.v1.json, task/clarification-log.v1.json, and task/clarification-summary.md
optionally consumes deterministic clarification responses from task/clarification-response.v1.json
if readiness stays NOT_READY, Qrane marks the run as BLOCKED / RUN_WAITING_FOR_INPUT instead of treating intake clarification as a generic failure
only clarification asks user questions; no mid-run questioning is allowed after readiness is accepted
does not mutate the canonical task input

4.2 `qonstrictor.py`

Canonical pre-plan constraint gate. Responsibilities:

evaluate task readiness before planning proceeds
turn declared constraints into effective runtime constraints
emit deterministic pass/review/fail output to qontract.d/
stop planning when intake readiness or scope rules are violated (fallback guard after clarification gate)

4.3 `instruqtor.py`

Planning agent. Responsibilities:

read the current tasq
create briqs in briq.d/
generate QONTRACT files on the first build pass
honor sensitivity settings and decomposition logic

4.4 `calqulator.py`

Local estimation helper. Responsibilities:

estimate token/cost footprint
annotate planning flow with rough cost expectations
zero AI-token cost
default estimation target is gemini / gemini-2.5-flash-lite
per-project overrides remain supported via agents.calqulator

4.5 `construqtor.py`

Code generation / modification agent. Responsibilities:

consume briqs
write or update files in qodeyard/
emit execution summaries to exeq.d/
use contract-aware and validation-aware build retries

4.6 `inspeqtor.py`

Review agent. Responsibilities:

run deterministic checks
optionally run smoketest checks via smoqetester (scoped or full mode)
run AI-assisted review stages
emit final recap material to reqap.d/
drive success / partial / failure assessment logic
classify validation execution mode as NONE, STATIC_ONLY, EXECUTED, or MIXED using explicit evidence (not markdown presence alone)

4.7 `qontextor.py`

Context indexing helper. Responsibilities:

build deterministic structural maps in qontext.d/, including per-file extractor metadata and a run manifest
run in local mode according to config
provide cheaper context reuse than shoving full source trees into prompts

4.8 `qompressor.py`

Deterministic multi-language structural skeletonizer. Responsibilities:

compress code structure into bloq.d/, including a run manifest that records native vs fallback processing paths
preserve useful structure while stripping bulky implementation bodies
support first-class skeletonization for Python, shell, JS/TS, and HTML/CSS in the shipped/provisioned environment
use Tree-sitter as an optional fallback for unsupported parseable languages when explicitly installed; default tests report its status honestly and an opt-in integration path can exercise it for real
reduce prompt weight for later iterations

4.9 `qontrabender.py`

Cache composer / variable-fidelity helper. Responsibilities:

assemble cache payloads
use policy-driven selection rules
practically relevant when Gemini context caching is the chosen path

4.10 `qonfirmer.py`

Deterministic contract verifier. Responsibilities:

enforce machine-readable invariants from qontract.json
catch forbidden imports / schema mismatches / endpoint rules / ID strategy violations

4.11 `qualifier.py`

Deterministic local verifier. Responsibilities:

syntax checks
import resolution checks
structural consistency checks
pluggable language-aware validation (Python, shell, JS/TS, HTML, plain CSS)

4.12 `lib_ai.py`

Unified provider abstraction. Current provider support in the repo:

OpenAI
Gemini
Anthropic
DeepSeek
Qwen
OpenRouter
Venice (v1.3.12 — Venice API, OpenAI-compatible)
mlx (v1.3.12 — local/LAN OpenAI-compatible runtimes)
llama-cpp (v1.3.12 — local/LAN OpenAI-compatible runtimes)

Also handles timeout / retry behavior and provider-specific adapters.

5. QONTRACT system

QONTRACT is the repository’s constitution-like enforcement layer.

Generation

On the first build pass, InstruQtor creates:

qontract.d/qontract.md
qontract.d/qontract.json

Use later in the pipeline

Later build passes and repair passes expect contract material to exist. The runtime uses fail-fast checks so later stages do not silently proceed without the contract.

Current documented invariant types

The current repo / doc / code set indicates checks around:

forbidden imports
exact field expectations
forbidden field names
ID type rules
monotonic ID strategy patterns
required endpoints

6. Context and memory layers

Layer	Location	Role
Task	`tasq.d/` / `worqspace/tasq.md`	current objective
Contract	`qontract.d/`	project invariants
Current code	`qodeyard/`	canonical current output
Execution summaries	`exeq.d/`	per-briq execution trace
Reviews	`reqap.d/`	review and iteration recap
Skeleton cache	`bloq.d/`	compressed architecture view
Structural context map	`qontext.d/`	lighter-weight context intelligence
Cache payloads	`qache.d/`	Qontrabender output when used
Logs	`struqture/`	console and event traces

7. Configuration reference

Main config file:

worqspace/config.yaml

Important top-level sections

retry
interleaved
verification
agents
options

Notable current settings

retry

enabled
max_attempts
stop_on_briq_fail
retry_delay

interleaved

enabled
local_validation
ai_quick_review
retry_on_review_fail

verification

enabled
checks.syntax
checks.imports
checks.skeleton_match

agents.construqtor

provider: AI provider (openai, gemini, anthropic, etc.)
model: model name
coding_mode: heredoc | direct | hybrid
- heredoc: Legacy Markdown fenced-block output.
- direct: Tool-based direct editing in an attempt-workspace.
  - Uses write_file_direct tool.
  - Hardened via safe_write_file with validation-root jail.
  - Features cumulative repair-forward validation within the loop.
  - Fallback to fenced blocks if tools are missing but files are present.
- hybrid (default): Deterministic per-file transport policy.
  - Default: new file creation uses heredoc; edits to existing files use direct.
  - One-way anti-flapping lock: direct can escalate to heredoc on deterministic failure triggers.
  - Attempt manifests include transport decision records and fallback reasons.

agents.inspeqtor.smoketest

enabled (default: false)
mode (scoped or full)
timeout_seconds
max_output_chars
adapters.<adapter>.enabled
adapters.<adapter>.command / commands (optional manual overrides)
adapters.<adapter>.append_changed_files
adapters.python.auto_unittest_discover
adapters.python.auto_cli_help
adapters.js_ts.auto_tsc_no_emit
adapters.js_ts.allow_script_execution
adapters.js_ts.require_dependencies

Smoketest output semantics:

per-check evidence includes execution_kind (static or executed)
validation_execution_mode only becomes EXECUTED / MIXED when genuine executed evidence exists
static-only checks (for example tsc --noEmit or shell syntax checks) do not inflate executed coverage

options

use_qompressor
use_qontextor
use_qontrabender
cheqpoint
max_total_iterations (legacy alias: auto_cycle_limit)
max_build_passes
cycle_estimate_mode (advisory or scheduler)
briq_sensitivity
mode

repair

max_attempts_per_build_pass (legacy alias: max_attempts)
same-run repairs consume max_total_iterations budget but do not increment max_build_passes

Important reality check about defaults

The committed repo config is a working example config, not a universal recommendation. CLI overrides and per-project tuning are expected.

8. Providers and API keys

QonQrete checks provider usage against required environment variables.

Environment variables used by the repo

OPENAI_API_KEY
GOOGLE_API_KEY
GEMINI_API_KEY
ANTHROPIC_API_KEY
DEEPSEEK_API_KEY
QWEN_API_KEY
OPENROUTER_API_KEY
VENICE_API_KEY          # v1.3.12 — required when provider: venice
MLX_API_KEY             # v1.3.12 — optional, used when provider: mlx
LLAMA_CPP_API_KEY       # v1.3.12 — optional, used when provider: llama-cpp

Current provider notes

Gemini can use GOOGLE_API_KEY or GEMINI_API_KEY
DeepSeek support is built through an OpenAI-compatible adapter inside lib_ai.py
Venice support is built through an OpenAI-compatible adapter; it requires a dedicated VENICE_API_KEY and does not fall back to OPENAI_API_KEY
mlx and llama-cpp support are built through an OpenAI-compatible adapter; they require api_base_url in the per-agent config block and work with or without an API key
local is used for non-remote helper agents

9. IDE integrations

9.1 VS Code extension

Location:

vscode-extension/

What it currently does

command palette commands for init / run / resume / clean / show status
right-click run support for tasq.md
right-click “run as QonQrete tasq” for other Markdown files
sidebar control panel
status bar state updates
shell detection and verification
qage browsing helpers
settings-backed run defaults aligned to current runtime (sensitivity=1, cycles=1, autonomous=true)
run option wiring includes --no-sync (qonqrete.noSync) and --seed-repo

Important current behavior

it executes the existing CLI in a terminal-driven way
it assumes a repo-local QonQrete project
it does not magically replace the core runtime
it does not yet implement the separate “central engine shared across many normal repos” flow

Packaging

cd vscode-extension
npm install
npm run compile
npx vsce package

9.2 IntelliJ / JetBrains plugin

Location:

intellij-plugin/

What is present in this repo snapshot

Gradle plugin project
plugin README / changelog
manual packaging path
tool-window-oriented UX concept for running and browsing QonQrete flows
settings + run dialogs wired to current launcher options, including --no-sync

Packaging

cd intellij-plugin
./gradlew buildPlugin

Important current behavior

Like the VS Code extension, the bundled IntelliJ plugin in this repo wraps the existing repo-local QonQrete CLI workflow.

10. Security model

The repository is designed around defense in depth.

Container security

isolated Qage container runtime
reduced capabilities
read-only root patterns with writable work areas
non-root execution with no runtime privilege transition
tmpfs / resource-limiting patterns in runtime setup

File/path safety

Implemented helper concepts include:

jail enforcement
path validation
symlink-aware checks
size limits for key files

Provider safety

lib_ai.py and related code enforce:

timeout handling
bounded retry behavior
sanitized error reporting

11. Current limitations

These limitations should be documented honestly for v1.4.5:

Repo-local workflow remains the active implementation model. The central engine / per-project metadata architecture is a future/product direction, not the current repo behavior.
IDE store publishing is outside the core runtime itself. The repo includes the extension/plugin projects and packaging paths, but that is distinct from the runtime behavior.
Experimental paths remain experimental. The standard CLI and IDE wrappers are the maintained execution surfaces.
Provider/model lists are whatever the current config and code support. Documentation should not invent providers or models that the repo does not actually implement.
Qontrabender is not universally useful for every provider path. The repo repeatedly documents its practical relevance to Gemini-oriented caching workflows.

12. Workspace Deployment (v1.2.0+)

Deployment model

The IDE integrations now support one-click workspace deployment:

Deploy to Workspace downloads a versioned release zip and extracts it into <workspace>/.qonqrete/
The runtime remains fully script-relative — qonqrete.sh derives SCRIPT_DIR from its own location
User-facing tasq.md lives at workspace root; the IDE syncs it into .qonqrete/worqspace/tasq.md before runs
Auto-init builds the container image on first run if missing
.qonqrete/ is automatically added to .gitignore

Command flow

Install extension/plugin
  → Deploy to Workspace
  → Create tasq.md
  → Configure Run (optional)
  → Run Tasq (auto-init if needed, auto-sync tasq)

Image versioning

Container images are now tagged with the version:

qonqrete-qage:1.4.0 (example current version)
qonqrete-qage:latest (convenience alias)
qonqrete-qage (untagged compatibility alias)

13. Cost Confirmation Gate (GateQeeper)

QonQrete supports an optional cost confirmation gate after CalQulator estimates the run cost.

Configuration

In worqspace/config.yaml:

options:
  cost_confirmation_gate: false   # default: false

When set to true, after CalQulator finishes, the GateQeeper prompts:

GateQeeper: Cost estimate above. Proceed with this run? [y/N]

The user must confirm before ConstruQtor begins. This prevents accidental expensive runs.

Behavior

Only triggers after CalQulator completes successfully
Skipped if CalQulator is skipped (e.g., local construqtor)
In non-interactive usage with closed stdin, the gate defaults to No and cancels the run

14. OpenRouter Provider Support

OpenRouter is supported as a provider through its OpenAI-compatible API endpoint.

Configuration

agents:
  construqtor:
    provider: openrouter
    model: anthropic/claude-sonnet-4

Environment variable

export OPENROUTER_API_KEY='...'

Supported models (via OpenRouter)

anthropic/claude-sonnet-4
openai/gpt-4.1
google/gemini-2.5-pro
deepseek/deepseek-chat-v3
Any model available on OpenRouter’s platform

15. Venice Provider Support (v1.3.12)

Venice is supported as a provider through its OpenAI-compatible API endpoint at https://api.venice.ai/api/v1. A real Venice model ID is set in the agent’s model field (not a profile selector — Venice uses actual model identifiers).

Configuration

agents:
  construqtor:
    provider: venice
    model: "qwen3-coder-480b-a35b-instruct-turbo"
    # api_base_url: "https://api.venice.ai/api/v1"   # default, override only if proxying
    venice_parameters:
      include_venice_system_prompt: false
    # max_tokens: 8192
    # context_window: 131072

Environment variable

export VENICE_API_KEY='...'

VENICE_API_KEY is required. Venice does NOT fall back to OPENAI_API_KEY. qrane fails early with a clear error if the key is missing while any agent is configured for provider: venice.

Example Venice models

The user may set any valid Venice text model ID. The following is a representative list at v1.3.12 release time; the authoritative list is always GET https://api.venice.ai/api/v1/models:

venice-uncensored
qwen3-coder-480b-a35b-instruct-turbo
qwen3-235b / qwen3-235b-a22b-instruct / qwen3-235b-a22b-thinking
qwen3-next-80b
qwen3-4b
qwen-2.5-qwq-32b
qwen-2.5-coder-32b
qwen-2.5-vl
mistral-31-24b
mistral-small-3.2-24b-instruct
llama-3.3-70b
llama-3.2-3b
llama-3.1-405b
dolphin-2.9.2-qwen2-72b
deepseek-r1-671b
deepseek-r1-llama-70b
deepseek-coder-v2-lite
claude-opus-4.6
claude-sonnet-4.6
glm-5
glm-4.7-flash-heretic
minimax-2.5

The model string is passed through verbatim — QonQrete does not enforce or hardcode any specific Venice model.

`venice_parameters` pass-through

When venice_parameters is set under a Venice-configured agent, QonQrete passes the entire dict through to the request body under the venice_parameters key (via the OpenAI SDK’s extra_body). It is never transformed. By default QonQrete does NOT disable Venice’s system prompt; set include_venice_system_prompt: false explicitly if you want that behavior.

16. MLX and Llama-cpp Provider Support (v1.3.12)

The mlx and llama-cpp providers are designed for local or LAN OpenAI-compatible LLM runtimes (e.g. MLX server, llama.cpp server).

Configuration

agents:
  construqtor:
    provider: mlx                              # mlx | llama-cpp
    api_base_url: "http://localhost:8080/v1"   # REQUIRED
    # model: "optional-model-string"
    # max_tokens: 8192
    # context_window: 16384

api_base_url is required for actual usage and must be set in the per-agent config block. If the model field is omitted or empty, QonQrete allows the upstream runtime to choose the model (the model field is omitted from the outbound JSON payload). This is achieved via a dedicated direct HTTP request path for these providers.

qrane does not fail on missing API keys for these providers — they run without authentication by default.

Environment variables (optional)

export MLX_API_KEY='...'         # used when provider: mlx
export LLAMA_CPP_API_KEY='...'   # used when provider: llama-cpp

Both are optional. If present, the matching key is sent as Bearer auth. If absent, the request proceeds without auth.

Profile defaults

Provider	`context_window`	`max_tokens`
`mlx`	16384	8192
`llama-cpp`	8192	4096

Per-agent context_window / max_tokens overrides take priority over these defaults.

QonQrete Release Notes

v1.4.5 — MLCon Edition: Truthful Inspection, Controlled Sync, IntelliJ Hardening & License Update

This release consolidates the full MLCon 2026 arc — from the pre-conference sprint through live demo validation to post-conference IntelliJ hardening and license cleanup.

Truthful Inspection & Execution Control

Final qodeyard/ files are authoritative review evidence with deterministic snippet metadata
Verdict synthesis prioritizes deterministic gates over advisory noise
Plan/build/review/repair flows are structured with bounded repair loops
-N/--no-sync skips repo-root sync-back; outputs stay in qage/qonstruction paths for inspection

Runtime UX

Reduced heartbeat chatter, concise default stream rendering with optional raw mode
ConstruQtor defaults to hybrid coding mode

Provider & Model Alignment

Primary defaults: venice / deepseek-v3.2 for primary AI agents
Provider and model selection configurable per agent
Local runtime support via mlx and llama-cpp

IntelliJ Plugin — Full JetBrains Ecosystem Coverage

Verified compatibility with all IntelliJ-based IDEs: IDEA, PyCharm, WebStorm, GoLand, CLion, RubyMine, Rider, DataGrip, PhpStorm
Resolved class loading issues on 2023.x IDE builds
Fixed NoClassDefFoundError for ProgressManager on certain JetBrains runtime versions
Corrected PluginException on startup for fresh installations
CI matrix covers IntelliJ Platform 2023.2 through 2026.1 (eight parallel runners)

Canonical Versioning & Installer Hygiene

Root VERSION file is the single source of truth across runtime, IDE plugins, and CI
qonqrete.sh reads QONQ_VERSION from VERSION (fail-loud on missing/empty)
The single install.sh at repo root is the source of truth, placed directly into the nginx image
Versioned release archive qonqrete-v1.4.5.zip

License Update

LICENSE updated

v1.3.12 — Hardened `direct` Coding Mode & Determinism

Significant upgrades to ConstruQtor’s tool-based coding system and execution determinism.

ConstruQtor Hardening

Mode-Aware Prompt Building: Monolithic prompts split into strategy-specific builders. direct mode now receives a clean tool-first contract with no heredoc leakage.
Hardened Direct Write: All tool-based writes now route through safe_write_file with a mandatory validation-root jail. Rejects path traversal and symlink escapes.
Cumulative Sandbox Validation: Repair-forward loop now validates the full cumulative candidate delta in the attempt workspace, catching cross-file regressions early.
Robust Fallback: If tool calls are absent, the system now automatically falls back to fenced Markdown block extraction if present, or fails loudly if no usable output exists.
Manifest Propagation: coding_mode is now explicitly recorded in all attempt manifests and build reports for downstream auditability.

Determinism & Stability

Sorted Sandbox Diffs: os.walk iterations are now sorted, ensuring deterministic changed-file discovery order.
Deterministic Staging: File staging and commit sequences are sorted by relative path for stable manifests.
Strict Config Validation: coding_mode is strict and fails loud on invalid values.

v1.3.0 — Hardened Sandbox, Agent Renames, Legacy Cleanup

Major security hardening, agent identity cleanup, and removal of accumulated legacy compatibility layers.

Security & Container Hardening

gosu eliminated — container runs as qrane via Dockerfile USER directive. No root phase, no privilege transition at runtime.
HOST_UID build-arg matching — on Linux/WSL, container qrane UID matches host user UID at build time. Bind-mounted files are natively owned by the host user. No chmod/chown helpers needed.
Zero capabilities — --cap-drop=ALL with no caps added. Combined with --security-opt=no-new-privileges to block any re-escalation.
Read-only rootfs — --read-only on the container, dev code mounts (qrane/, worqer/) mounted :ro.
Hardened tmpfs — /tmp and /home/qrane/.cache mounted with noexec,nosuid,nodev.
docker-entrypoint.sh eliminated — umask inlined in Dockerfile ENTRYPOINT. One less file, one less attack surface.
API key passthrough — keys passed via -e KEY (env passthrough) instead of -e KEY=VALUE (argv exposure).
Helper containers deleted — fix_qage_permissions and engine_run_helper removed entirely. UID matching makes them unnecessary.
File permissions tightened — dirs 0750, files 0640, world gets nothing. No more a+rwX sprays.

Agent Renames

guard.py → qonstrictor.py (Qonstrictor)
qontract_guard.py → qonfirmer.py (Qonfirmer)
loqal_verifier.py → qualifier.py (Qualifier)
Display-name override system deleted — agent display names now derive from filenames via .replace('q','Q').

Engine & Build

Podman preferred over Docker in auto-detection (rootless-native, no daemon).
Buildx is Docker-only — podman always uses plain builds.
CONTAINER_ENGINE env override bug fixed (was captured after being blanked).
Image tag includes host UID on Linux/WSL for per-user cache correctness.
Resource limits removed — container gets full host resources.

Versioning

VERSION file is the single source of truth. No hardcoded fallbacks.
Variable naming unified: QONQ_V → QONQ_VERSION everywhere.
QONQ_VERSION passed to container via -e at runtime, not baked into image.
IMAGE_NAME_LEGACY tag removed (was duplicate of :latest).

Legacy Removal

--legacy-cycle-continuation flag removed from CLI.
legacy_cycle_continuation_enabled() function deleted.
promote_reqap() function deleted (was the legacy reqap→tasq continuation path).
QONQ_LEGACY_QAGE_ID and QONQ_CANONICAL_RUN_ROOT env vars removed.
runs/ and state/ directories deleted — no more symlink tracking. resolve_target_qage uses filesystem timestamps.
legacy_alias parameter renamed to agent_name throughout manifest system.
All legacy_* manifest field names cleaned.

Shell Script Cleanup

set -euo pipefail restored (was set -uo due to a landmine in print_runtime_info() — fixed with return 0).
PY_ARGS converted from string to bash array — no shell-injection surface.
resolve_absolute_path() rewritten using python3 os.path.abspath — no edge-case bugs.
Manifest parsing via python3 json.load, not grep | sed.
save_qonstruction_core() extracted from duplicate save paths.
Dead code removed: CONFIG_FILE, host_gid(), shadow symlinks, IMAGE_NAME_LEGACY.
copy_dir_contents excludes .DS_Store and ._* automatically.

IDE Plugins

Phantom CLI flags (--tui, --msb, --wonqrete) removed from both VS Code and IntelliJ.
Agent config editors updated: tasqleveler → qrystallizer, added qonstrictor.
Stale entrypoint.sh references removed from deploy actions.
VS Code dead import (ALL_API_KEYS) removed.
Secret management verified: VS Code uses SecretStorage (OS keychain), IntelliJ uses PasswordSafe.

CI/CD

runtime-release.yml updated — removed stale entrypoint.sh, Sandboxfile, root qonqrete.jpg.

Documentation

README image path fixed (qonqrete.jpg → qrane/qonqrete.jpg).
All docs updated to current agent names and CLI flags.
Version strings synchronized to 1.3.0 across all manifests.

v1.2.0 — Workspace Deployment & Hassle-Free Bootstrap

This is the first globally-publishable release of both the VS Code extension and IntelliJ plugin. Users can now install QonQrete from the IDE marketplace and be productive in under a minute — no manual cloning, no command line setup.

Headline: One-Click Workspace Deployment

Both IDE integrations now implement identical workspace-local deployment:

Install the extension/plugin
Run “QonQrete: Deploy to Workspace”
Create a tasq.md at your project root
Run — auto-init handles the rest

The runtime deploys into <workspace>/.qonqrete/ as a hidden directory, keeping the project clean. The user-facing tasq.md lives at the workspace root. The IDE syncs it into the runtime before each run.

New commands (both IDEs)

Command	What it does
Deploy to Workspace	Downloads versioned release zip → extracts to `.qonqrete/` → validates → updates `.gitignore`
Create tasq.md	Creates a starter template at workspace root and opens it
Run Tasq	Now auto-syncs root tasq, auto-inits if image missing, offers Deploy if runtime not found

Core runtime changes

Versioned image naming: qonqrete-qage:1.2.0 (also tagged :latest and legacy untagged for backward compat)
Runtime remains fully script-relative — zero architectural disruption

VS Code extension v1.2.0

New: Deploy to Workspace command with zip download + git clone fallback
New: Create tasq.md command
New: Auto-init on first Run Tasq (builds container image automatically)
New: Root tasq.md sync before every run
New: .gitignore auto-management
New: .qonqrete/qonqrete.sh added to path discovery (preferred over legacy paths)
New: Sidebar Deploy + Create Tasq buttons
Updated: Status bar suggests Deploy when runtime not found
Updated: Welcome message offers Deploy
Updated: Activation events include .qonqrete/qonqrete.sh

IntelliJ plugin v1.2.0

New: Deploy to Workspace action with zip download + git clone fallback
New: Create tasq.md action
New: Auto-init on first Run Tasq
New: Root tasq.md sync before every run
New: .gitignore auto-management
New: .qonqrete/qonqrete.sh in path discovery (preferred)
New: Tool window Deploy + Create Tasq buttons
Updated: RunTasq offers Deploy when runtime missing, Create tasq when tasq missing
Updated: Versioned image detection

Backward compatibility

Legacy paths (qonqrete.sh at workspace root, qonqrete/qonqrete.sh subdirectory) remain as fallback detection
Legacy untagged qonqrete-qage image name still checked
Existing worqspace-only workflows continue to work
No changes to core runtime architecture

v1.1.9-stable

This release syncs the repository around the v1.1.9-stable state and reflects the biggest shift since v1.0.4-stable: QonQrete is no longer just a core CLI runtime — the repo now also includes IDE integrations for VS Code and JetBrains tooling.

(See previous release notes for v1.1.9 and earlier details.)

Qompressor Skeletons (v1.4.5)

Qompressor creates deterministic structural skeletons in bloq.d/ from qodeyard/.

Current First-Class Paths

Python AST skeletons
Shell skeletons via shfmt -tojson when available
JavaScript/TypeScript via repo-shipped TypeScript helper
HTML via parse5
CSS via postcss

Optional fallback:

Tree-sitter for unsupported parseable languages when explicitly installed via requirements-optional-tree-sitter.txt

Why Use It

preserve architecture-level context without shipping full implementation bodies
keep context predictable and inspectable on disk
support iterative runs with smaller prompt payloads

Capability Check

python worqer/qompressor.py --capabilities

VS Code Extension Usage (v1.4.5)

What It Is

The VS Code extension wraps the existing QonQrete CLI workflow inside VS Code.

Current AI Configuration Surface

Targets the four primary runtime agents:

qrystallizer
instruqtor
construqtor
inspeqtor

Default binding: venice / deepseek-v3.2.

Local-only providers (mlx, llama-cpp) are supported by runtime config but not shown in the shared provider/model picker.

Key Commands

QonQrete: Run Tasq
QonQrete: Resume Run
QonQrete: Init Workspace
QonQrete: Clean Qages
QonQrete: Show Status
QonQrete: Set AI Configuration

Current Run Options Wired in UI

sensitivity (--briq-sensitivity)
cycles (--cyqles)
mode (--mode)
autonomous (--auto)
no sync (--no-sync)
qonstruction name (--qonstruction-name)
seed repo (--seed-repo)
container engine (--docker/--podman)

`--no-sync` Behavior

When enabled, repo-root sync-back is skipped and outputs remain in qage/qonstruction paths.

Packaging

cd vscode-extension
npm install
npm run compile
npx vsce package

IntelliJ Plugin Usage (v1.4.5)

What It Is

The IntelliJ plugin wraps the existing repo-local QonQrete CLI workflow for JetBrains IDEs.

Current AI Configuration Surface

Targets the four primary runtime agents:

qrystallizer
instruqtor
construqtor
inspeqtor

Default binding: venice / deepseek-v3.2.

Local-only providers (mlx, llama-cpp) remain runtime-supported but are not shown in the shared provider/model picker.

Core Actions

Run Tasq (Ctrl+Alt+Q)
Run any markdown as task input
Init workspace
Resume run
Clean qages
Show status
Set AI configuration

Current Run Options

The tool window/settings align with launcher options including:

--no-sync
--seed-repo
--briq-sensitivity
--cyqles
--mode
--auto

Packaging

cd intellij-plugin
./gradlew buildPlugin

Install From Disk

Use the generated ZIP in build/distributions/.

QonQrete Quickstart

Option A: IDE-First (Recommended)

VS Code

IntelliJ / JetBrains

What happens

Option B: CLI (Power Users)

Prerequisites

1. Install + init runtime

2. Edit the task

3. Run QonQrete

4. Resume / Clean

IDE Commands Reference

Recommended first-run sanity checks

Cost Confirmation Gate

Validation Reality

Configuration (v1.4.5)

Core Files

Key Sections in config.yaml

Repair and Iteration Controls

ConstruQtor Coding Modes

Repo Seeding and Sync Controls

Provider and Model Configuration

Required and Optional Environment Variables

Useful Runtime Commands

QonQrete Architecture

High-level model

Top-level layout

Layer 1 — Host entrypoint

qonqrete.sh

Layer 2 — Qrane orchestrator

qrane/

Runtime responsibilities

Layer 3 — Agent layer

worqer/

AI / pipeline agents

local / deterministic helpers

Pipeline order

Artifact model

Meaning of the main directories

QONTRACT enforcement model

Generation

Enforcement

Context / memory layers

Security model

IDE integration architecture

VS Code

IntelliJ / JetBrains

Current repo-local model

Data flow summary

Qontextor extractor model

Related docs

Workspace Deployment Model (v1.2.0+)

Key design decisions

Deployment source

QonQrete Terminology

Core runtime terms

Workflow terms

Structural artifact terms

Agent names

Runtime/config terms

Runtime engine terms

IDE integration terms

Important terminology honesty note

Memory Model (v1.4.5)

Primary Memory Surfaces

Resume Semantics

Sync and Containment

Testing and Validation (v1.4.5)

Core Runtime Checks

Capability Reporting

Python Test Suite (repo-local)

Validation Reality

Contexting in QonQrete (v1.4.5)

Context Layers

Why This Matters

Current Runtime Notes

Capability Checks

QonQrete Documentation

Current release deltas (v1.4.5 - MLcon Edition)

Table of contents

Key Sections in `config.yaml`

`qonqrete.sh`

`qrane/`

`worqer/`

Current release deltas (`v1.4.5 - MLcon Edition`)

4.1 `qrystallizer.py`

4.2 `qonstrictor.py`

4.3 `instruqtor.py`

4.4 `calqulator.py`

4.5 `construqtor.py`

4.6 `inspeqtor.py`

4.7 `qontextor.py`

4.8 `qompressor.py`

4.9 `qontrabender.py`

4.10 `qonfirmer.py`

4.11 `qualifier.py`

4.12 `lib_ai.py`