Cival Trapped Traders v1.2.1 - Install Guide

Indicator for ATAS Platform. One file: Cival.TrappedTraders.dll. Display name in ATAS: Cival Trapped Traders (category Cival). Support: support@civalsystems.com.

1. Requirements

Need	Detail
Platform	ATAS Platform 8.0.15 or newer, Windows. The DLL targets the .NET 10 runtime that ATAS ships; you install nothing extra.
Footprint / cluster data	The chart history must carry bid and ask volume at each price for every bar you want analysed. This is the one hard data requirement. Many feeds supply candles only; with those, the indicator reports Footprint unavailable and draws nothing.
History	At least 21 completed bars are needed before the first reading can appear (a 20-bar reference window plus the source bar). Load several days. By default the indicator analyses the newest 5,000 bars of the chart (setting Maximum chart slots at rebuild).
Chart	Start on a regular time-based chart; the worked examples in these docs use 5-minute bars. The engine reads completed bars in order.
Tick size	ATAS must report the instrument's real tick size, and the footprint rows must sit on that price grid. Rows that do not are rejected as "off-grid".

2. Install with the included script (recommended)

Step 1. Close ATAS completely (every ATAS window; check Task Manager for leftover ATAS processes).

Step 2. Extract the ZIP to an ordinary folder, for example Downloads\Cival-Trapped-Traders-v1.2.1.

Step 3 (optional). Integrity check, in PowerShell from the extracted folder:

Get-FileHash .\ATAS\Cival.TrappedTraders.dll -Algorithm SHA256
Select-String -Path .\SHA256SUMS.txt -Pattern 'Cival.TrappedTraders.dll'

The two hashes must match (letter case does not matter).

Step 4. Run the installer from the extracted folder:

.\ATAS\Install.ps1

It copies the DLL into %APPDATA%\ATAS\Indicators, backs up a DLL of the same name if one is already there, and verifies the SHA-256 of the copy. If Windows blocks the script because it came from the internet, run Unblock-File .\ATAS\Install.ps1 once (or powershell -ExecutionPolicy Bypass -File .\ATAS\Install.ps1) and try again.

Step 5. Start ATAS.

3. Manual install

Close ATAS.
Copy ATAS\Cival.TrappedTraders.dll into %APPDATA%\ATAS\Indicators (paste that path into Explorer's address bar).
If a file with that name is already there, move it out of the Indicators folder first (keep your backup elsewhere; do not leave two copies in the folder).
If Windows marked the file as downloaded, right-click it, choose Properties and tick Unblock, or run Unblock-File on it.
Start ATAS.

4. First load

Open a chart of an instrument whose history has footprint data. A quick check: temporarily switch the chart to a cluster/footprint view and confirm bid x ask numbers appear in each candle, then switch back if you prefer.
Open the chart's Indicators window (right-click the chart, then Indicators), search for Cival Trapped Traders, and add it.
Leave every setting at its default for now. If you want to set the baseline explicitly, set Apply a starting preset to Balanced (it equals the defaults).
Wait for history to load. A heads-up display (HUD) titled CIVAL TRAPPED TRADERS appears in the top-right corner of the price pane. It needs a pane of at least 190 x 110 pixels.

The first HUD line is a status. What the common ones mean:

First HUD line	Meaning
Warmup / Warmup: prior ATR / volume baseline	Not enough earlier bars yet: 14 for the ATR baseline and, because Require prior-relative volume is on, 20 for the volume baseline. Normal for the first bars after loading.
Footprint unavailable: `<reason>`	The newest closed bar has no usable bid/ask rows. The reason names the check that failed (for example No reported price rows). Fix the data, not the settings.
Waiting for known structure reference	Footprint is fine but no reference level exists yet (for example the 20-bar window is not full, or no confirmed swing has formed).
Active: closed-bar failed-aggression hypotheses	The detector is running. Having no zones on screen is normal.
Waiting for valid native tick size	ATAS has not supplied a tick size for the instrument.
AS OF bar N; later candles excluded from study	Review mode is on (setting Review as of bar).

The last HUD lines read Closed classified coverage 100% (how much of the newest closed bar's volume carries a bid/ask classification; at least 99% is required) and the reminder Failed-aggression hypothesis / positions and exits unknown. With no qualified zone the HUD says NO QUALIFIED TRAP / inspect data and filters.

5. Verify it works

Tick every line:

[ ] Cival Trapped Traders appears in the indicator list and adds without an error message.
[ ] The HUD titled CIVAL TRAPPED TRADERS is visible (or Show dashboard is on and the pane is large enough).
[ ] After at least 21 completed bars, the first HUD line reads Active: closed-bar failed-aggression hypotheses (not Footprint unavailable).
[ ] The HUD's coverage line reads Closed classified coverage with a value of 99% or more.
[ ] A gold line reads LIVE preview / forming bar N / may change (or Live preview waiting for ticks until the first tick arrives). This is the provisional layer, not a confirmation.
[ ] The settings window lists 85 settings in numbered groups (00 Chart clarity through 99 Export).
[ ] Review test: set Review as of bar to a bar number inside your loaded history (the CONFIRMED @ n and source n numbers shown by the indicator are such numbers). The first HUD line changes to AS OF bar N; later candles excluded from study. If it says Review bar is outside the bounded loaded history, choose a more recent number. Set it back to -1 when done.
[ ] If you scroll back through history and find any zone, hovering a candle inside it switches the HUD to that zone.

Seeing no zones for a while does not mean the install failed. Zones need a qualifying source, a reclaim and a later confirmation (see 03-Reading-the-Indicator).

6. Updating

Save your chart template first (your indicator settings live in your ATAS workspace and chart templates, not in the DLL).
Close ATAS and run the new version's .\ATAS\Install.ps1. It backs up the DLL it replaces.
Start ATAS and reopen your chart. If ATAS was left running, it may offer Reload indicators in the main window's status bar; reopening ATAS is the safe alternative.
If an older saved chart shows fewer layers than the docs describe, open the indicator settings and switch on Apply upgraded visual defaults now (group 89 Live visuals). It switches on live preview, trap cards, confluence checklist, edge-extended boxes, arrows, zones, labels, unconfirmed candidates, ended zones, markers and the dashboard, and sets fill opacity 26% and minimum box height 10 pixels.

7. Uninstalling

Close ATAS, then run .\ATAS\Uninstall.ps1 from the extracted folder, or delete Cival.TrappedTraders.dll from %APPDATA%\ATAS\Indicators by hand. Charts that used the indicator will no longer show it. Exports, if you made any, stay in %APPDATA%\ATAS\CivalTrappedTraders (or your chosen folder) until you delete them.

8. Troubleshooting

Symptom	Likely cause and fix
Not in the indicator list	ATAS was not restarted after copying; the DLL is not directly in %APPDATA%\ATAS\Indicators; Windows blocked the file (Properties, Unblock); ATAS is older than 8.0.15; or you searched a partial name. Search the exact name Cival Trapped Traders.
HUD says Footprint unavailable: No reported price rows (or "waiting for footprint")	Your data connection supplies candles without bid/ask volume per price, or the footprint history for those bars is not loaded. Load tick/cluster history or use a connection that provides it. No setting substitutes for missing data.
Footprint unavailable: Incomplete volume/classification reconciliation	The bar's bid + ask volume does not add up to its candle volume within 1% (or under 99% classified). A partial or filtered footprint. Reload history; do not lower Minimum classified candle volume percent to hide it.
Footprint unavailable: Invalid/duplicate/off-grid footprint row	Rows are not on the instrument's tick grid, or a price repeats. Check the tick size ATAS shows for the instrument.
HUD never appears / panel empty	The price pane is smaller than 190 x 110 px; Show dashboard is off; or the HUD sits behind another panel. Enlarge the pane, change Dashboard corner or Dashboard width.
Warmup does not end	Fewer than 21 completed bars are loaded, or the baselines keep resetting because bars are malformed. Load more history.
Nothing drawn, status Active	Normal when no candle met the source rules. Check that Detect failed breakout aggression, Detect extreme aggression rejection and Detect stranded diagonal stacks are on. Do not loosen settings to force output.
Gold zones appear but never confirm	By design confirmation is delayed. Read the HUD checklist and check the reclaim deadline (8 bars), the confirmation window (4 bars after reclaim), the displacement test (0.25 frozen ATR from the reclaim close) and the close-location test (0.60). A near miss does not confirm. See 03-Reading-the-Indicator section 17.
Too many zones on the chart	Lower Maximum recent visible zones, switch Show ended confirmed zones off, or use the compact layout (Full analysis detail off, Compact display on).
Copy fails: file in use / DLL locked	ATAS is still running. Close every ATAS window and process, then run Install.ps1 again.
Settings reset after an update	ATAS stores settings by name in the chart template. Restore your saved template, or re-enter the settings. Keep a template copy before each update.
A setting change seems ignored	A combination was rejected as invalid and the earlier values stay in force (the status line shows Invalid trapped-trader settings). Common cases: Minimum later bars after reclaim greater than Maximum bars after reclaim; manual upper reference not above the manual lower reference while Structural reference is ManualLevels.
No alerts	Enable new live local alerts is off by default; alerts also stay silent during history loading, recalculation, review mode and delivered history corrections.
Export did nothing	The status line says why: No completed report to export, or Export failed: `<error type>`.