This works fine, but I'd like to take the extra step of programatically creating a menu and assigning it to 'main-nav', set to automatically add new pages.

This theme is being used as a starting point for a wordpress install, so I'd like to include this functionality to save a little bit of time on the repetitive tasks such as manually creating these menus via appearance -> menus.

great answer, and very useful info - but I still do want to create the menus themselves programatically. I know I don't have to but whenever I install my theme the first thing I do is create the main nav menu as 99% of the time it is always a custom menu. Your point about wp_nav_menu falling back is good to know though :)
–
jammypeachFeb 22 '13 at 13:46

Why do you want to reinvent the wheel? Why bother with programmatically creating custom navigation menus to be assigned to Theme Locations, when WordPress already provides much easier ways to ensure that those Theme Locations can display dynamic menus, with no intervention necessary?
–
Chip BennettFeb 22 '13 at 13:57

Because when I make a WP site, most of the time I want a specific set of top-level pages in the nav menu (not all of them). This means install wp -> install theme -> add some example pages -> add menus, which is inefficient when you do it 10 times. It would be a time-saver to auto-generate the menu on theme install, then make appropriate edits later. The other side of the coin is that the theme is used by some of my collegues and I often have to go in and create the main nav menu for them; they don't realise it needs to be created each time.
–
jammypeachFeb 22 '13 at 14:06

if you know of an easier / simpler way to acheive that I'm definitely all ears :)
–
jammypeachFeb 22 '13 at 14:07

Downsides to this is that if the admin deletes the main navigation menu, it will get created again (which could get annoying) - so I've included the create menu code in a function which only runs once, on theme install. There are no pages added with this code, but having suitable menues defined and already assigned to their theme-locations will simplify matters for non-coders creating sites with my theme, and no more questions about why certain pages are showing in the nav menu when a nav menu hasn't been created yet :)