# RowTether quickstart

## Install

Close the editor. Copy the complete RowTether folder into your C++ project's Plugins directory. Generate project files and build the Development Editor target using Unreal 5.8 and its supported C++ toolchain. Enable RowTether under Edit > Plugins and restart. Open Tools > RowTether. Windows Editor only; this Editor module is not loaded by packaged games. Only engine modules are dependencies.

## Review

1. Select all consumer DataTables you want to inspect in the Content Browser. Include the CSV destination table if comparing an import.
2. Click Use selected DataTables. The panel lists exactly the selected DataTables. Other asset types are not added. Rules for retained tables are preserved; rules belonging to removed tables are removed after confirmation, and the CSV candidate selection is cleared.
3. Row handles are detected automatically. A Name or String column is considered a relationship only when it appears in an explicit profile. Load a JSON profile after selecting its source tables. The default treats row handles as required; a rule for that handle property can mark it nullable. Its actual handle destination remains authoritative.
4. For CSV comparison, choose the destination from the selected DataTables and choose a CSV. Either order works; once both are selected, comparison starts automatically. Use Clear comparison to return to current checks. The candidate is read, not imported.
5. Review tables starts a fresh run. Cancel or close the panel to stop collecting. Sources may be loaded into memory, but RowTether does not save, rename, reimport, repair or mark them dirty. Avoid editing tables while reviewing; detected changes fail the review and prevent export.
6. Read the status and coverage before interpreting findings. Double-click a finding to open the source DataTable, then find the reported row and property in its editor.
7. Export report creates a new run directory below the directory you choose. Incomplete results require the separate Export incomplete report action. A duplicate run destination is never replaced.

## Profile schema 1

Store shared profiles in your project's Config/RowTether. The directory is not created by plugin startup. Save profile as writes only when explicitly requested and refuses existing files. Results may be placed in Saved/RowTether; they are local and are not automatically transmitted.

```json
{
  "schemaVersion": 1,
  "maxRecords": 10000,
  "rules": [
    {
      "tablePath": "/Game/RowTetherExample/Consumers.Consumers",
      "propertyPath": "Link",
      "targetTablePath": "",
      "nullable": true
    }
  ]
}
```

All rule fields are required. A source must be selected. Duplicate mappings, nested property paths and future schema versions are rejected before source collection. For user-defined structures use the authored property name. Arbitrary Name properties are never inferred as foreign keys. Top-level arrays and sets of row handles are inspected. Nested references, maps, static arrays and unsupported containers are not inspected for relationships; their omission produces Partial with a reason.

## Separate test project

The commercial plugin contains no sample tables, Content folder or Examples directory. Training data belongs to a separate test project. Open its Content/RowTetherExample folder, select Targets and Consumers, load Fixtures/BundledHandles.json and click Review tables: expect two current errors. Select the destination DataTable Targets and choose Fixtures/Candidate.csv: once both are selected, comparison starts automatically and should show two additional warnings for C1/C2. For clean data, select Targets and ConsumersValid, load Fixtures/BundledValid.json and clear the candidate destination.

## Reproducible CSV examples

The downloadable fixtures contain CSV and JSON inputs, not automatically installed assets. Create a user-defined structure with a `Label` String property, and another with a `Link` Data Table Row Handle property. Create Targets using the first structure and Consumers using the second under /Game/RowTetherExample. Import Targets.csv, then Consumers.csv. Load nullable-handles.json after selecting both tables.

The tables have ten rows each. C1/C2 use T1, C3 uses T2, C4 uses a missing row, C5 has a null destination and key T1, C6-C10 are empty optional handles. Expect two current errors. Candidate.csv contains T2-T10 and should produce exactly two additional warnings for C1/C2. ConsumersValid.csv is the corrected example: all nonempty handles resolve. It should have no current errors. Import files yourself only into these new example tables, never into production tables. Candidate.csv is chosen in RowTether, not imported.

For an explicit Name column instead, create the same structure with Link of type Name and use a rule pointing to Targets. Optional empty/None values are accepted. Nonempty keys must resolve.

## CSV contract

UTF-8 CSV with comma separators, quoted fields and doubled quotes is accepted. The first column is Name, the exported `---`, or the table's configured ImportKeyField. The remaining headers must exactly cover the authored table columns (case-insensitive); duplicate headers and duplicate FName keys are rejected. Field counts and quote structure must be valid. Only row identities and schema headers determine removal impact; no arbitrary cell import hooks execute. A case-only name change is informational because Unreal FName identity is case-insensitive. The original source remains untouched, including for invalid candidates.

## Coverage and limits

Completed means the declared, supported relationships in the selected consumer scope were processed. It does not mean the entire project was searched or that findings are absent. Partial indicates limits, unsupported properties or an invalid candidate. Cancelled discards the unfinished snapshot; run again before making a decision. NoApplicableData describes an empty input. Failed indicates the request could not run or a source changed during collection; failed results discard inconsistent findings and cannot be exported.

Default budget: 10,000 consumer rows and at most 10,000 captured relationships. The profile can set 1-100,000. Destination key indexes are capped at 100,000 per table; larger/unusable destinations are unresolved with Partial coverage, not fabricated missing-row failures. CSV is limited to 16 MiB in the panel, profile JSON to 1 MiB, and requests to 1,000 source tables and rules. Collection runs in small game-thread batches. Reviews above 256 captured rows evaluate a UObject-free snapshot on a worker; asset loading and export use the editor thread. Cancellation discards unfinished work. Performance measurements must accompany any future responsiveness claim.

## Stable codes

| Code | Meaning | Next step |
|---|---|---|
| ROWTETHER-TABLE-MISSING | Destination DataTable is absent/unavailable | Inspect the declared path or row handle |
| ROWTETHER-ROW-MISSING | Destination exists but row key is absent | Review row spelling and destination data |
| ROWTETHER-REFERENCE-INVALID | Row key cannot be represented by Unreal | Shorten the key and check the source field |
| ROWTETHER-REFERENCE-EMPTY | Required key is empty/None | Supply a key or explicitly mark the relation nullable |
| ROWTETHER-GAME-RULE | A declared game rule fails or cannot be evaluated | Check the rule outcome, applicability and required fields |
| ROWTETHER-ROW-REMOVED | Candidate removes a row used by this consumer | Review the named consumer before importing |
| ROWTETHER-CSV-INVALID | Candidate syntax/schema/key is ambiguous or invalid | Correct the CSV; impact is not reported as complete |
| ROWTETHER-CASE-CHANGE | Spelling changes but FName identity does not | Informational; it is not a removed row |

## Export and local support

The JSON schema includes plugin/engine versions, run identity, source/profile fingerprints, coverage, omissions, all captured relations and finding evidence. Fingerprints identify captured semantics and are not security signatures. Identical inputs produce stable semantic ordering; run IDs differ. CSV protects spreadsheet formula prefixes; HTML escapes all source text and has no scripts. JSON is the authoritative typed report; CSV/HTML summarize findings.

Exports stage beside the final run directory, read back all outputs, then publish by a same-volume rename. Existing exports are preserved. Filesystem links/reparse points and traversal in the output root are rejected. Choose an ordinary local directory if a cloud placeholder or junction is rejected. Only the current temporary files are cleaned up on failure. Review the report yourself before sharing: paths, row names and values can contain project information. There is no automatic upload, telemetry, listener or Telegram integration.

Out of scope: automatic rewriting/renaming, arbitrary FName searches, inferred relationships, complete Blueprint graph analysis, packaged games and unverified engine/platform combinations.

## Further workflows

**Review this table** in the DataTable editor runs a one-table review with the active policies and game rules. It does not compare a CSV or replace the general panel selection. For Name/String profiles, game rules and the complete finding-resolution flow, use the [online RowTether guides](/docs/rowtether/).

To resolve a finding, read its code and coverage first, fix the intended source row, destination, profile or rule, then run a fresh review. Disabling a rule or removing a table can hide a finding; it does not prove that the data is correct. See [Resolve a finding](/docs/rowtether/resolve-finding).

The optional AI workflow requires the separately distributed `RowTetherTools` package, Epic’s Unreal MCP and Toolset Registry plugins, and a compatible client. Follow [Connect RowTether to AI](/docs/rowtether/ai-setup). If the package was not supplied with your project delivery, contact support; do not use an undocumented copy.

## Contact
Support: support@nomomicantpause.com. Include versions, a finding code and a minimal reproduction. Review any exported project information before sharing it.


## Public documentation and local preferences
The public guide is available at https://nomomicantpause.com/docs/rowtether/. Support: support@nomomicantpause.com. Last-used dialog directories are stored locally in Saved/RowTether/preferences.json after explicit file actions; opening the panel does not scan assets or write preferences.