# IFVG Desk v1.2.0 — quick start

## First chart

1. Open standard candles on an intraday TradingView chart. Start on **1 minute** so the default **5 / 15 / 30 minute** context frames are all higher.
2. Paste the complete [indicator source](../src/IfvgDesk.pine) into Pine Editor and add it to the chart. Read any actual compiler/runtime message before interpreting an empty chart.
3. Check the session settings. The intended baseline is **09:30–11:00 New York**. The exchange/chart display timezone does not redefine the script's New York clock.
4. Choose the entry mode: **inversion close** evaluates the confirmed flip; **retest** waits for a later touch and directional rejection close.
5. Read the main state and its reason, then the context lanes and factor rows. Leave optional gates off until you understand what they require on your feed.

Auto selects 5/15/30m on 1m and 3m charts, and 15/30/60m on 5m. When choosing manual frames, all three lanes must satisfy chart < A < B < C, including disabled lanes. A 5m context on a 5m chart is not higher-timeframe context.

At baseline, only the entry-session gate is required. Other factor rows remain visible, but their gates are off. Enable the HTF gate to require aligned gap overlap; enable sweep, displacement, bias or SMT separately. The default ten-bar swing, one-tick buffer, 1R target and one completed plan/day are transparent starting rules, not tuned instructions for your account.

## Read the desk in ten seconds

| State | Read it as |
|---|---|
| WAIT | No eligible inversion. The reason line says whether fresh gaps are on the chart and what would arm one. |
| ARMED · LONG / SHORT | An IFVG exists; the reason line names it and what it is waiting for (a required check that is not met, or the next trigger). No trade is implied. |
| LONG / SHORT · PLAN ACTIVE | A paper plan is open. The PLAN rows show entry, stop and target with their distances and R, plus the size estimate. |
| DAY DONE | The daily resolved-plan limit was reached; entries resume on the next New York day. The desk keeps tracking context. |

The ribbon reads 01 GAP → 02 FLIP → 03 CHECKS → 04 PLAN: ✓ marks a done step, CHECKS shows required-met / required-enabled in amber while an armed zone waits, PLAN lights only while a plan is open. The context lanes show the nearest valid gap per frame with an ALIGNED mark (✓ the gap points the way the analysed side would trade, ✗ it points the other way) and WHERE it sits versus the last close. Another aligned gap may satisfy the HTF check even if the nearest displayed gap points the other way. The checks table lists required checks first: ● required must be met on the entry bar, ○ optional is shown for context and never blocks; **required** and **met** are different things.

The active Co-Pilot reports planned R from the actual entry/stop/target levels, so outward tick rounding can make it differ from the requested target multiple. Quantity text rounds to at most eight decimal places; it preserves a nonzero quantity at the minimum allowed step but is not an arbitrary-precision display. Factor rows describe the current closed analysis candle, not a frozen explanation of an older entry.

The indicator starts with a Medium, Compact dashboard at Top Right and a Standard Co-Pilot at Bottom Right. "Dashboard rows = Full" adds the paper record, the latest audit ID reference and the event tape. Try Large on a full desktop display if the text is too small; use Small or Compact on a shorter chart. Tags at the right edge (lane tags, the 09:30 open) sit twelve bars past the last candle: give the chart a right margin, or move the dashboard to a left position, when the panel covers them. The strategy starts in Minimal view with its dashboard and Co-Pilot off, so Strategy Tester has more space.

CE is the gap's midpoint. Fresh FVGs are subdued; inverted zones are stronger. Used or invalid zones stop extending. The event tape records the most recent transitions. The Co-Pilot explains the same state in sentences; adjust its depth or position when it covers the candles you want to inspect.

“Earlier plans visible” counts completed plans in addition to the active plan. Each New York session is identified by its dated start, so consecutive loaded session-only chart days start a new session range even without an out-of-session bar between them. An overnight session keeps its range across midnight; the daily resolved-plan cap still resets by New York date.

## Trace a decision with setup history

1. Keep **06 · Setup audit trail → Record setup history** on (the default).
2. Enable **Audit · setup history → Show setup history**. It is hidden by default and works independently of the dashboard. Its default Bottom Left position moves if a visible dashboard or narrative already uses that position.
3. Read the latest eight saved events. **Setup history page · newest first** selects older pages; an out-of-range page clamps to the last available page. Row times use New York time and show month/day plus hour/minute.
4. Hover a row to inspect the full Setup ID, exact saved reason, gap/close context and JSON snapshot. The displayed ID is shortened; do not paste that abbreviation into a filter.
5. Set **06 · Setup audit trail → Setup ID filter · blank = all** to the full ID from the tooltip or Pine Logs. The panel and exported report now match that exact ID. Recording and entry selection still cover all setups. Clear the filter to show all retained events again.

Each Setup ID has the form `symbol|frame|birth-open-ms|bull/bear`. The last part is the original gap direction; the panel's LONG/SHORT side is the intended inverted trade direction. Events record the decision candle's close time as UTC Unix milliseconds, even though the panel renders New York time.

The stored reason is fixed when the confirmed event happens and stays fixed within that run. A reload, settings change, symbol/frame change or data recalculation rebuilds the history using the available bars and current settings. The latest **300 events across all setups** are retained by default, up to 500; the footer reports older records removed. A filtered setup can therefore be missing its birth or earlier decisions. Filtering does not reserve storage for it. Non-overlapping bars in retest mode are not logged, and three-candle patterns that fail the birth filters never become recorded setups.

## Copy a diagnostic report

1. Use an editable personal copy pasted into Pine Editor. Published studies cannot produce Pine Logs. Open **Pine Logs** from the editor's More menu; see [TradingView's debugging documentation](https://www.tradingview.com/pine-script-docs/writing/debugging/).
2. Keep recording on, choose the full Setup ID filter or leave it blank, then enable **06 · Setup audit trail → Write bug report to Pine Logs**.
3. After historical calculation finishes, copy the report header/settings and matching retained event JSON lines. Later matching realtime events are appended only when their bars confirm. The panel is newest first; the historical export is chronological.
4. Save the copied text with the symbol/feed, timeframe and the problem timestamp using [the bug report template](bug-report-template.md). Include the header even when reporting just one setup, so settings and retention limits travel with it.
5. For Strategy Tester differences, also record **Strategy Properties** separately, including commission, slippage and fill/recalculation options. Core audit settings describe the paper engine; they cannot read user overrides in the broker emulator's Properties.

The option writes diagnostics to your Pine Logs pane. It does not create a TradingView alert, send a message or submit a bug report. Copy the records before changing settings or reloading; the audit is bounded and recalculated, not a saved account history. Details and event meanings are in [the v1.2 audit guide](audit-trail-v1.2.md).

## Optional SMT

Choose a comparator symbol explicitly. For index comparisons, select a feed whose session and timestamps match the chart you are studying. Direct relationship compares like-direction extremes; inverse relationship uses the opposite side of the comparator. The implementation uses a disclosed prior-bar rolling-range comparison, not an inferred copy of a discretionary pivot method.

If SMT reads unavailable, check the symbol, data access and matching bars. Enabling the SMT gate while its data is unavailable prevents that candidate from passing; missing data is never treated as confirmation.

Select a **valid ticker using the symbol picker**. A nonexistent ticker can trigger TradingView's Invalid symbol validation before Pine runs. This differs from a valid ticker with no current matching bars: the latter was checked on gold with QQQ outside regular hours and correctly displayed NO DATA with the gate still required.

## Inspect the strategy companion

1. Add [the strategy source](../src/IfvgDeskStrategy.pine) to a standard candle chart.
2. Match the indicator's engine inputs, entry mode and sessions. Visual settings do not define the signal rule.
3. Set commission and slippage for the instrument in Strategy Properties. Set planned cash risk and quantity step in Inputs: the strategy passes that quantity explicitly, so Properties' default order size does not override it. Check symbol point value and quantity increments; cash risk uses symbol currency. The initial cost assumptions are 2.25 per contract per fill and one tick of slippage, which you must replace if they do not describe your instrument.
4. Record the symbol/feed, timeframe, chart session, date range, rule switches and costs alongside the result. Keep empty samples and losing cells in the log.
5. Change one rule at a time and compare a separate period before treating an apparent improvement as informative. When testing new defaults, add a fresh study or reset inputs; updating source can retain old input values.

The paper ledger resolves ambiguous stop/target bars stop-first. The broker emulator may use a different bar path and fills, and its costs alter outcomes. Compare the records as different models, not as numbers that must match exactly. [TradingView's strategy documentation](https://www.tradingview.com/pine-script-docs/concepts/strategies/) explains its simulation assumptions.

## If something looks wrong

| Symptom | Check |
|---|---|
| No entries | Session, daily lock, entry mode, enabled gates, unavailable SMT and loaded history. An inversion alone is not enough. |
| Invalid timeframe message | All three frames, including disabled lanes, must satisfy chart < A < B < C. |
| Context appears later than expected | The desk waits for a confirmed higher-timeframe bar. |
| Old zones disappear | Age and retained-zone limits are deliberate. |
| The panel covers price | Move the panel/Co-Pilot, choose Compact rows or a smaller size, lower depth or select Focus/Minimal view. |
| Lane tags or the 09:30 tag are hidden behind the panel | They sit twelve bars past the last candle. Give the chart a right margin (scroll or drag the price scale) or place the dashboard on the left. |
| TradingView's legend covers a left-side panel header | Use right-side panel placement, or hide the relevant chart Status line legend items: symbol logo/title, OHLC/bar change and indicator titles/values. These are TradingView chart presentation settings, separate from the script's panel controls. |
| Candles cross an opaque panel after updating older source | Remove and re-add the current script so its visual-order declaration is applied; updating an existing instance can retain the old order. |
| Strategy Co-Pilot moves differently from the indicator | Its optional label uses the chosen side and recent price range. It is attached to chart coordinates, while the indicator's Co-Pilot is fixed to a screen position. |
| Strategy differs from paper record | Fill timing, intrabar assumptions, costs, sizing and paper-paced signal eligibility. |
| A settings change did not affect a test | Reset the saved study's inputs or add a fresh study. |
| Setup history is empty | Check Record setup history, loaded bars and an exact full-ID filter. Clear the filter to inspect all retained events. |
| A setup's birth or old decision is missing | Check the removed-record count and global event cap. Filtering does not restore discarded events. Birth-filter failures and non-overlapping retest bars are not recorded as setup events. |
| A skipped entry's reason differs from today's checklist | The checklist is current context; the history row is the frozen reason on that earlier decision candle. |
| No Pine Logs appear for the published study | Paste the open source into an editable personal copy and enable Write bug report to Pine Logs there. |

For alerts, use the indicator's named conditions for individual lifecycle events, or its enabled JSON alert() calls for accepted paper entries. An inversion alert can occur without an entry. The structured message includes the audit's stable `setup_id`, source zone and confirmed close, levels, sizing estimate, observed factors and enabled gates. It is an event format, not a broker automation service.

## เริ่มใช้งานแบบย่อ

เปิดกราฟแท่งเทียนปกติ **1 นาที** แล้วนำไฟล์ IfvgDesk.pine ไปใส่ใน Pine Editor ค่าเริ่มต้นใช้กรอบบริบท 5 / 15 / 30 นาที และเวลา New York อ่านสถานะหลักกับเหตุผลก่อน: **ARMED คือมีโซน IFVG รอเงื่อนไข ยังไม่ใช่สัญญาณเข้า** ส่วน LONG / SHORT คือมีแผนจำลองที่ผ่านกฎแล้ว

บรรทัดใต้สถานะบอกเหตุผลเสมอ (โซนไหน รออะไร หรือแผนที่เปิดอยู่) ตาราง CHECKS เรียงข้อที่ "จำเป็น" ไว้ก่อน ● จำเป็นต้องผ่าน ○ แสดงเป็นบริบทเท่านั้น ส่วน PLAN บอกว่ากฎจะทำอะไรต่อไปพร้อมระดับราคาจริงเมื่อมีแผน

เวอร์ชัน 1.2.0 เพิ่มประวัติราย Setup ID: เปิด **Show setup history** เพื่อดูเหตุการณ์ครั้งละ 8 รายการ แล้วชี้ที่แถวเพื่อดูเหตุผลที่บันทึก ณ แท่งปิดและ ID เต็ม ใช้ **Setup ID filter** เพื่อติดตามโซนเดียวกันได้ ค่าเริ่มต้นเก็บ 300 เหตุการณ์รวมทุก setup และแจ้งจำนวนที่ถูกตัดออก การเปลี่ยนกราฟหรือค่าตั้งจะคำนวณประวัติใหม่ หากต้องการแนบรายงาน ให้ใช้สำเนาส่วนตัวใน Pine Editor แล้วเปิด **Write bug report to Pine Logs** และคัดลอกข้อมูลตาม [แบบฟอร์มรายงาน](bug-report-template.md) ระบบไม่ได้ส่งรายงานออกไปเอง

ตัวเลขบนหน้าจอเป็นบันทึกจำลองที่ยังไม่หักต้นทุน หากต้องการศึกษาผลภายใต้ต้นทุน ให้ใช้ IfvgDeskStrategy.pine และตั้งค่าค่าธรรมเนียม/slippage ให้ตรงเครื่องมือที่ใช้ บันทึกจำลองกับ Strategy Tester ใช้สมมติฐานการออกต่างกัน จึงไม่จำเป็นต้องเท่ากัน ดูหลักฐาน engine เวอร์ชัน 1.0.1 ใน [review2-report.md](review2-report.md) และการตรวจชั้นแสดงผล 1.1.0 ใน [display-v1.1.md](display-v1.1.md) ส่วน build-report.md และ measurements.md เก็บผลตรวจและผลทดลองเดิมของเวอร์ชัน 1.0.0