A kit update merges cleanly or it doesn't, almost entirely based on decisions you made while
building your product, not decisions the kit's authors made while shipping the update. Three habits
keep the merge painless.

## Don't edit the plumbing in place

Extend through the documented seams instead of modifying kit files directly: add a new integration
in `app/adapters/`, add a new feature by copying the example slice's shape rather than editing it,
add configuration rather than rewriting an initializer's internals. A kit file you never touched
merges cleanly by definition; there's nothing for git to reconcile. See
[The Adapter+Fake Pattern](/docs/building-features/the-adapter-fake-pattern) and
[Adding a Resource](/docs/building-features/adding-a-resource) for the seams themselves.

## Keep your product code in clearly separate files

Your own models, controllers, and views, living in files the kit itself never touches, rarely
conflict with an incoming update no matter how much the kit changes elsewhere. The risk isn't in
adding new files; it's in editing shared ones.

## Expect conflicts to concentrate in files you customized

The landing page, the design tokens, `app_identity.rb`: these are exactly the files
[Making It Yours](/docs/getting-started/making-it-yours) told you to edit, and they're also the
files most likely to see a conflict on a future merge, since both you and a kit update might touch
the same lines. That's expected, not a sign something went wrong. Resolve those by hand, favoring
your own product-specific values, and the rest of the merge fast-forwards without any intervention.

## Next

See where kit changes are actually documented:
[Release Notes](/docs/upgrading-releases/release-notes).