# AGENTS.md — CB-C6s-STU-GSI-Fixes

## Overview

TWRP flashable zip for the **CB-C6s-STU** tablet (Spreadtrum/Unisoc) running a
GSI. It appends `build.prop` properties, installs a touchscreen IDC config,
and installs a camera sensor config. All install logic lives in a shell-script
`update-binary` — no compiled code, no build system.

## Build / Package

```bash
# Create the flashable zip (excluded from git via .gitignore)
cd /home/purpl/Repos/CB-C6s-STU-GSI-Fixes
zip -r ../CB-C6s-STU-GSI-Fixes.zip META-INF/ system/ vendor/
```

No build dependencies, no lint, no test suite.

## Architecture

```
zip root
├── META-INF/com/google/android/
│   ├── update-binary        ← Entry point: POSIX sh script, executed by TWRP
│   └── updater-script       ← Dummy placeholder (TWRP ignores it)
├── system/
│   ├── build.prop           ← Properties APPENDED (>>) to /system/build.prop
│   └── usr/idc/
│       └── goodix_ts.idc    ← Copied to /system/usr/idc/goodix_ts.idc (644)
└── vendor/etc/
    └── sensor_config.xml    ← Copied to /vendor/etc/ or /system/vendor/etc/ (644)
```

### Install flow (update-binary)

1. Locate zip root: `dirname $0` → up 4 levels (`../../../../`)
2. Mount `/system` and `/vendor`
3. **Append** `system/build.prop` → `/system/build.prop` (backup first to `.bak`)
4. Copy `goodix_ts.idc` → `/system/usr/idc/`
5. Copy `sensor_config.xml` → `/vendor/etc/` (fallback to `/system/vendor/etc/` for SAR)
6. Report success via `ui_print()` to `/proc/self/fd/$OUTFD`

### Critical constraint: build.prop is APPENDED, never replaced

`update-binary` now uses **key-based dedup**: each line is appended only if its
key (`key=` before `=`) does not already exist in the target.

```sh
# 去重追加：逐 key 检查，仅追加不存在的条目
while IFS= read -r line || [ -n "$line" ]; do
  case "$line" in
    ''|'#'*) continue;;
  esac
  key="${line%%=*}"
  if ! grep -q "^${key}=" /system/build.prop 2>/dev/null; then
    echo "$line" >> /system/build.prop
  fi
done < "$BUILDPROP_SRC"
```

Re-flashing is now safe — entries are never duplicated.

## Key Files

| File | Role |
|------|------|
| `META-INF/…/update-binary` | Entire install logic (shell script) |
| `META-INF/…/updater-script` | Placeholder; not executed |
| `system/build.prop` | 5 properties appended to device's build.prop |
| `system/usr/idc/goodix_ts.idc` | Touchscreen input device config (orientation + type) |
| `vendor/etc/sensor_config.xml` | Camera module mapping: hi846, gc8034 (rear/front, 4 combos) |
| `README.md` | User-facing documentation |
| `.gitignore` | Excludes `*.zip` |

## Coding Conventions

- **Shell**: POSIX sh, no bashisms. Shebang `#!/sbin/sh` (TWRP environment).
- **Error handling**: `abort()` helper exits with message. `2>/dev/null` on
  non-critical operations (mount, mkdir, cp backup).
- **Naming**: `UPPER_CASE` for globals/file paths, `snake_case` for helpers.
- **Partition logic**: `/vendor` mount is best-effort; falls back to
  `/system/vendor/etc/` when `/vendor/etc/` doesn't exist (SAR compatibility).

## Git Workflow

- Branch: `main` (root commit only)
- Commit style: concise summary line, then bullet list of changes
- `.gitignore`: excludes `*.zip` (the build artifact) and tooling directories

## Tips for AI Agents

- **This is not a software project** — there is no build system, no package
  manager, no test runner. Changes are edits to shell script or config files.
- **To add a new fix**: add the payload file under `system/` or `vendor/`,
  add a step to `update-binary` with `ui_print` and `cp` (or append logic),
  update `README.md` "What it fixes" table.
- **To add a new build.prop property**: append a line to `system/build.prop`.
  If it needs to be idempotent, add a grep guard in `update-binary`.
- **Testing**: flash the zip in TWRP on the device. There is no emulation.
- **The `updater-script` is a dummy** — do not add Edify commands there; put
  all logic in `update-binary`.
- **Zip path**: the build artifact is written to the repo's parent directory,
  not inside the workspace. `*.zip` in `.gitignore` covers both locations.